chore: improve public-facing documentation

2026-09-14 04:15:53 -05:00 · 2026-04-09 01:51:12 -04:00
parent e4e0d4f7c1
commit 523ddd2d8e
7 changed files with 105 additions and 22 deletions
--- a/AquaNet/src/libs/i18n/en_ref.ts
+++ b/AquaNet/src/libs/i18n/en_ref.ts
@@ -144,10 +144,9 @@ export const EN_REF_SETUP = {
  'setup.welcome': `Welcome! If you have a game set up, please follow the instructions below to set up the connection with AquaDX.`,
  'setup.keychip-warning': `Your keychip is linked to your account and should be kept secure. Do not give others your keychip.`,
  'setup.steps.one': `Pick a method of setting up network communications. Some browsers may not be able to do automatic setup.`,
-  'setup.steps.two': `Ensure your game has encryption disabled as AquaDX does not support encryption. This may be via a patch or setting.`,
-  'setup.steps.three': `Link your Aime card to your AquaDX account using the <a href="/cards">Cards</a> page via it's access code or serial number.`,
-  'setup.steps.four': `Start the game. Upon reaching the title screen, the network icon in the corner should now show green instead of grey.`,
-  'setup.support-info': `If you need assistance, feel free to make an inquiry in a <a href="/support">support channel</a>.`,
+  'setup.steps.two': `Link your Aime card to your AquaDX account using the <a href="/cards">Cards</a> page via it's access code or serial number.`,
+  'setup.steps.three': `Start the game. Upon reaching the title screen, the network icon in the corner should now show green instead of grey.`,
+  'setup.support-info': `If you need additional assistance, feel free to make an inquiry in a <a href="/support">support channel</a>.`,
  'setup.reveal-keychip': `Reveal keychip`,
  'setup.type.automatic': `Automatic Setup`,
  'setup.type.manual': `Manual Setup`,
@@ -155,7 +154,16 @@ export const EN_REF_SETUP = {
  'setup.automatic': `Select your segatools.ini below to autofill the network information.`,
  'setup.automatic.success': `Success, data has been updated`,
  'setup.automatic.failure': `Failed to update information, please ensure access is not blocked and try again.`,
-  'setup.automatic.select': `Pick file`
+  'setup.automatic.select': `Pick file`,
+  'setup.troubleshooting.header': 'Setup Troubleshooting (FAQ)',
+  'setup.troubleshooting.items.one': `"It shows DNS BAD on Network Test!"<br>
+    You likely misconfigured your segatools.ini. Ensure it's pointing to the DNS shown above (under Manual Setup).`,
+  'setup.troubleshooting.items.two': `"It shows タイトル サーバー BAD (Title Server BAD) on Network Test!"<br>
+    You should check your segatools.ini to ensure your keychip is set correctly.<br>
+    Additionally, Card Maker users and players using a game version higher than what's listed may need to disable encryption
+    <a target="_blank" href="https://gitea.tendokyu.moe/Dniel97/SEGAguide/wiki/SDED#patching-assemblycsharpdll">(instructions for Card Maker)</a>`,
+  'setup.troubleshooting.items.three': `"I can't scan my card!"<br>
+    Emulated card readers, by default, are configured to use the ENTER key to scan in (hold it).`
 }

 export const EN_REF_SETTINGS = {
--- a/AquaNet/src/libs/i18n/zh.ts
+++ b/AquaNet/src/libs/i18n/zh.ts
@@ -5,6 +5,7 @@ import {
  EN_REF_LEADERBOARD,
  EN_REF_MAI_PHOTO,
  EN_REF_SETTINGS,
+  EN_REF_SETUP,
  EN_REF_USER,
  EN_REF_USERBOX,
  type EN_REF_Welcome
@@ -154,6 +155,32 @@ const zhHome: typeof EN_REF_HOME = {
  'home.import.data-conflict': '继续导入将覆盖现有数据',
 }

+const zhSetup: typeof EN_REF_SETUP = {
+  'setup.welcome': `欢迎！如果您已经设置好游戏，请按照以下说明与 AquaDX 建立连接。`,
+  'setup.keychip-warning': `您的 keychip 与您的账户绑定，应妥善保管。请勿将 keychip 提供给他人。`,
+  'setup.steps.one': `选择一种网络通信设置方式。某些浏览器可能无法进行自动设置。`,
+  'setup.steps.two': `通过 <a href="/cards">Cards</a> 页面，使用访问码或序列号将您的 Aime 卡绑定到 AquaDX 账户。`,
+  'setup.steps.three': `启动游戏。在进入标题界面后，角落中的网络图标应显示为绿色而不是灰色。`,
+  'setup.support-info': `如果您需要更多帮助，请在 <a href="/support">support channel</a> 中提交咨询。`,
+  'setup.reveal-keychip': `显示 keychip`,
+  'setup.type.automatic': `自动设置`,
+  'setup.type.manual': `手动设置`,
+  'setup.manual': `请使用以下信息修改您的 segatools.ini 文件。`,
+  'setup.automatic': `选择您的 segatools.ini 文件以自动填充网络信息。`,
+  'setup.automatic.success': `成功，数据已更新`,
+  'setup.automatic.failure': `更新失败，请确保访问未被阻止后重试。`,
+  'setup.automatic.select': `选择文件`,
+  'setup.troubleshooting.header': '设置故障排除（FAQ）',
+  'setup.troubleshooting.items.one': `"网络测试显示 DNS BAD！"<br>
+    您可能错误配置了 segatools.ini。请确保其指向上方显示的 DNS（见手动设置）。`,
+  'setup.troubleshooting.items.two': `"网络测试显示 タイトル サーバー BAD（Title Server BAD）！"<br>
+    请检查您的 segatools.ini，确保 keychip 设置正确。<br>
+    此外，Card Maker 用户以及使用高于所列版本的玩家可能需要禁用加密
+    <a target="_blank" href="https://gitea.tendokyu.moe/Dniel97/SEGAguide/wiki/SDED#patching-assemblycsharpdll">（Card Maker 指南）</a>`,
+  'setup.troubleshooting.items.three': `"我无法扫描卡片！"<br>
+    默认情况下，模拟读卡器使用 ENTER 键进行扫描（按住）。`
+}
+
 const zhSettings: typeof EN_REF_SETTINGS = {
  'settings.title': '用户设置',
  'settings.tabs.profile': '个人资料',
@@ -342,5 +369,5 @@ export const zhAquaTrans: typeof EN_REF_AQUATRANS = {

 export const ZH = { ...zhUser, ...zhWelcome, ...zhGeneral,
  ...zhLeaderboard, ...zhHome, ...zhSettings, ...zhUserbox, ...zhMaiPhoto,
-  ...zhAquaTrans
+  ...zhAquaTrans,   ...zhSetup
 }
--- a/AquaNet/src/pages/Home/SetupInstructions.svelte
+++ b/AquaNet/src/pages/Home/SetupInstructions.svelte
@@ -93,13 +93,21 @@ id=${keychip}`.trim(), {
      <div class="setup-step">
        3. <div>{@html t('setup.steps.three')}</div>
      </div>
-      <div class="setup-step">
-        4. <div>{@html t('setup.steps.four')}</div>
-      </div>
-
+      <h2>{t('setup.troubleshooting.header')}</h2>
+      <ul>
+        <li>
+          {@html t('setup.troubleshooting.items.one')}
+        </li>
+        <li>
+          {@html t('setup.troubleshooting.items.two')}
+        </li>
+        <li>
+          {@html t('setup.troubleshooting.items.three')}
+        </li>
+      </ul>
      <p>
        {@html t('setup.support-info')}
-      </p>
+      </p>      
    {:else}
      <p>{t('loading')}</p>
    {/if}
@@ -111,6 +119,10 @@ id=${keychip}`.trim(), {
  .code
    overflow-x: auto

+  ul
+    li
+      margin: 0.75em 0
+
  :global(pre.shiki)
    background-color: transparent !important

--- a/README.md
+++ b/README.md
@@ -32,21 +32,22 @@ Multipurpose game server for ALL.Net games.
 > [!WARNING]  
 > CHUNITHM pre-NEW!! and maimai pre-DX are no longer supported after February 6th, 2026 and all associated data will be removed.

-| Game                   | Latest Ver.         | Initial Ver.        | Notes                                                       | Web UI | Data Import |
-|------------------------|---------------------|---------------------|-------------------------------------------------------------|--------|-------------|
-| SDHD: CHUNITHM         | 2.45 (X-VERSE-X)    | 2.00 (NEW)          |                                                             | ✅    |  ❗         | 
-| SDEZ: maimai DX        | 1.65 (CiRCLE PLUS)  | 1.00 (DX)           | Missing circle (teams) support                              | ✅    |  ✅         | 
-| SDGA: maimai DX (Intl) | 1.60 (CiRCLE)       | 1.00 (DX)           | Thanks [@Clansty](https://github.com/clansty)               | ✅    |  ✅         | 
-| SDED: Card Maker       | 1.39                | N/A                 | Thanks [@Becods](https://github.com/Becods)                 | ❌    |  ❌         | 
-| SDDT: O.N.G.E.K.I.     | 1.50 (Re:Fresh)     | N/A                 | Thanks [@PenguinCaptain](https://github.com/PenguinCaptain) | ✅    |  ❌         | 
-| SBZV: Project DIVA     | 7.10                | N/A                 | Minimal support                                             | ❌    |  ❌         | 
-| SDFE: Wacca            | 3.07 (Reverse)      | N/A                 | Later versions are EOS patches, network will not work       | ✅    |  ❌         | 
+| Game                   | Latest Ver.         | Initial Ver.        | Notes                                                       | Web UI | Data Import | Encryption |
+|------------------------|---------------------|---------------------|-------------------------------------------------------------|--------|-------------|------------|
+| SDHD: CHUNITHM         | 2.45 (X-VERSE-X)    | 2.00 (NEW)          |                                                             | ✅    |  ❗         | ✅        |
+| SDEZ: maimai DX        | 1.65 (CiRCLE PLUS)  | 1.00 (DX)           | Missing circle (teams) support                              | ✅    |  ✅         | ✅        | 
+| SDGA: maimai DX (Intl) | 1.60 (CiRCLE)       | 1.00 (DX)           | Thanks [@Clansty](https://github.com/clansty)               | ✅    |  ✅         | ✅        |
+| SDED: Card Maker       | 1.39                | N/A                 | Thanks [@Becods](https://github.com/Becods)                 | ❌    |  ❌         | ❌        |
+| SDDT: O.N.G.E.K.I.     | 1.50 (Re:Fresh)     | N/A                 | Thanks [@PenguinCaptain](https://github.com/PenguinCaptain) | ✅    |  ❌         | ✅        |
+| SBZV: Project DIVA     | 7.10                | N/A                 | Minimal support                                             | ❌    |  ❌         | 🔓        |
+| SDFE: Wacca            | 3.07 (Reverse)      | N/A                 | Later versions are EOS patches, network will not work       | ✅    |  ❌         | 🔓        |

 <!-- A majority of them have been left as N/A for initial version as they do not appear to have restrictions -->

 Check out these docs for more information.
 * [Game specific notes](docs/game_specific_notes.md)
 * [Frequently asked questions](docs/frequently_asked_questions.md)
+* [Encryption notes](docs/encryption.md)
  
 ## Usage

--- a/docs/encryption.md
+++ b/docs/encryption.md
@@ -0,0 +1,35 @@
+# Encryption Support
+
+AquaDX supports encryption for Chunithm, Maimai and Ongeki.<br>
+It is not required to connect and keys are NOT provided by default.
+
+Card Maker has encryption features in the client, but they are not supported due to it's complexity.
+
+## Adding new keys to AquaDX
+
+> [!IMPORTANT]
+> Ensure you're using AquaDX from source. Docker will work, as long as you use `docker-compose up --build`
+
+1. Create a new file at `src/main/resources/data/game/<game name>/game_encryption.json`
+2. Fill it out using the following schema:
+```json
+{
+    "code": "SDHD",
+    "versions": [215, 216],
+    "key": "DECAFBADDECAFBADDECAFBADDECAFBADDECAFBADDECAFBADDECAFBADDECAFBAD",
+    "iv": "DECAFBADDECAFBADDECAFBADDECAFBAD",
+    "salt": "DECAFBADDECAFBAD",
+    "iterations": 36
+},
+```
+
+**`key`, `salt`, and `iv` MUST be hex strings. Do NOT insert raw ASCII strings.**<br>
+
+Replace `code` with the correct code for your game (`SDHD` for Chunithm JP, `SDEZ` for Maimai JP, etc.).<br>
+Set `versions` to be an array of game versions without the decimal (215 for 2.15, 150 for 1.50, etc.).<br> 
+You MUST include rom patch versions in this array or it will not encrypt correctly.
+
+- Maimai DX does NOT use iterations, you do not need to include it
+- Ongeki always uses 64 iterations (you must include it)
+- If using a specific Python script to rip Chunithm keys, focus on the `=>` entries.
+- `key` is 32 bytes long. `iv` is 16 bytes long. `salt` is 8 bytes long. (hex strings should be twice as long as they are in bytes)
--- a/src/main/java/icu/samnyan/aqua/sega/general/filter/CompressionFilter.kt
+++ b/src/main/java/icu/samnyan/aqua/sega/general/filter/CompressionFilter.kt
@@ -43,7 +43,7 @@ class CompressionFilter(

        val game = path.split("/")[2]
        val version = path.split("/")[3].filterNot { it == '.' }.toInt()
-        return keys.find { it.version == version && it.code == game }
+        return keys.find { it.versions.contains(version) && it.code == game }
    }

    @OptIn(ExperimentalStdlibApi::class)
--- a/src/main/java/icu/samnyan/aqua/sega/general/model/EncryptionKey.kt
+++ b/src/main/java/icu/samnyan/aqua/sega/general/model/EncryptionKey.kt
@@ -6,7 +6,7 @@ import java.time.LocalDateTime

 class GameEncryptionKey {
    var code: String? = null
-    var version = 0
+    var versions: List<Int> = listOf()
    var key: String? = null
    var salt: String? = null
    var iv: String? = null