doc: improve documentation layout and list binary formats

.github/workflows/build-and-release.yml

@@ -32,7 +32,7 @@ jobs:
           dotnet-version: ${{ env.DOTNET_VERSIONS }}
 
       # Full test for master builds and PR of repo owners
-      - name: "Build, test, and bundle"
+      - name: "[Full] Build, test, and bundle"
         if: ${{ env.TEST_RESOURCES_URI != '' }}
         run: >
           dotnet run build.cs --
@@ -49,10 +49,11 @@ jobs:
           TEST_RESOURCES_PWD: ${{ secrets.TEST_RESOURCES_PWD }}
 
       # Tests without resources for PR of external contributors
-      - name: "Build, test, and bundle"
+      - name: "[Basic] Build, test, and bundle"
         if: ${{ env.TEST_RESOURCES_URI == '' }}
-        run: >
-          dotnet run build.cs -- --target=Default --target=Bundle --dotnet-configuration=Release
+        run: dotnet run build.cs -- --target=Default --target=Bundle --dotnet-configuration=Release
+        env:
+          TEST_RESOURCES_URI: ${{ secrets.TEST_RESOURCES_URI }}
 
       - name: "Publish artifacts to CI"
         uses: actions/upload-artifact@v7

.gitignore

@@ -9,14 +9,6 @@ build/temp/
 /CHANGELOG.md
 /CHANGELOG.NEXT.md
 
-# Test results
-test_results/
-
-# Documentation output
-docs/_site
-docs/api
-docs/_site_pdf
-
 # IDEs
 .vs/
 *.csproj.user

.prettierrc.yaml

@@ -0,0 +1,4 @@
+overrides:
+  - files: "*.md"
+    options:
+      proseWrap: always

.vscode/ltex.dictionary.en-US.txt

@@ -0,0 +1 @@
+koma

.vscode/settings.json

@@ -13,4 +13,7 @@
         "editor.formatOnType": true
     },
     "prettier.proseWrap": "always",
+    "cSpell.words": [
+        "Koma"
+    ],
 }

README.md

@@ -32,13 +32,14 @@ Done ✔️ To test / with issues ⚠️ Not done 🛑
 
 ### Scripts
 
-- **beta.sh:** generates a new beta translation rom if you have access to the Translation repo.
+- **beta.sh:** generates a new beta translation rom if you have access to the
+  Translation repo.
 - **copy_text_format:** generates a new text format.
 - The rest are testing scripts for devs.
 
 ## Tinke
 
-You can use [Tinke by PleoNex](https://github.com/pleonex/tinke) to unpack
+You can use [Tinke by pleonex](https://github.com/pleonex/tinke) to unpack
 containers and view .dig files.
 
 ## Build
@@ -78,17 +79,18 @@ Examples:
 
 ### Documents
 
-You can find these documents in our `docs/dev` folder:
+You can find these documents in our [`docs/articles/dev`](docs/articles/)
+folder:
 
 - Alar Specification
 - Text Specification
-- DTX Specification by PleoNex
-- DTX Research by PleoNex
+- DTX Specification by pleonex
+- DTX Research by pleonex
 - [FileFormats by Uknown Hacker](https://web.archive.org/web/20100111220659/http://jumpstars.wikispaces.com/File+Formats#toc10)
 
 ### Videos
 
-PleoNex did some research on Streaming:
+pleonex did some research on Streaming:
 
 - [DIRECTO ROM Hacking: Triple reto de imágenes](https://www.youtube.com/watch?v=r1Rsx6RRe1U)
 - [DIRECTO Domingos de desensamblador: imágenes de Devil Survivor y JUS y ordenar textos de MetalMax 3](https://www.youtube.com/watch?v=R2h-UEcO_-k)
@@ -97,12 +99,14 @@ PleoNex did some research on Streaming:
 ## Stack
 
 - C# / .NET 8.0
-- [Yarhl by PleoNex](https://github.com/SceneGate/Yarhl)
-- [PleOps.Cake by PleoNex](https://github.com/pleonex/PleOps.Cake)
+- [Yarhl by pleonex](https://code.pleonex.dev/sceneGate/yarhl)
+- [PleOps.Cake by pleonex](https://codeberg.org/pleonex/PleOps.Cake)
 
 ## Credits
 
-Special thanks to [PleoNex](https://github.com/pleonex) for his help, for Yarhl
-and PleOps.Cake. Thanks to [TraduSquare](https://tradusquare.es) for the
-inspiration and support. Thanks to the Jump Ultimate Stars! devs for this
-amazing game.
+Special thanks to [pleonex](https://fosstodon.org/@pleonex) for his help, for
+Yarhl, and PleOps.Cake.
+
+Thanks to [TraduSquare](https://tradusquare.es) for the inspiration and support.
+
+Thanks to the Jump Ultimate Stars! devs for this amazing game.

docs/.gitignore

@@ -0,0 +1,12 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site
+
+# DrawIO
+.$*.drawio*

docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/articles/dev/toc.yml

@@ -0,0 +1,7 @@
+# Disabled as there won't be releases in the near future.
+#- name: ✨ Changelog
+#  href: ../changelog.md
+
+- name: 📃 API docs
+- name: Namespaces
+  href: ../../api/toc.yml

docs/dev/DTX-Specification.md → docs/articles/specs/dtx.md

@@ -1,8 +1,9 @@
 # DTX Sprites
 
-DTX files contains sprites used in animations and UI layers. 
+DTX files contains sprites used in animations and UI layers.
+
+## Sprite Types
 
-## Sprite Types 
 We have some types:
 
 - Type 01: Unknown format.
@@ -15,11 +16,11 @@ We have some types:
 
 ## Tools and Specifications
 
-Use the [ImHex pattern file](./dtx.hexpat) to automatically parse and visualize DTX files in the [ImHex](https://imhex.werwolv.net/) hex editor. I fully recommend using this to explore the format.
+Use the [ImHex pattern file](./resources/dtx.hexpat) to automatically parse and visualize DTX files in the [ImHex](https://imhex.werwolv.net/) hex editor. I fully recommend using this to explore the format.
 
 In Ubuntu, copy it to `/usr/share/imhex/pattern` for automatic file recognition.
 
-### Tinke Workflow:
+### Tinke Workflow
 
 You can use my [Tinke branch](https://github.com/priverop/tinke/tree/feat/jus_dtx) to automatically watch DTX files. If you don't have it, follow these instructions:
 
@@ -31,7 +32,7 @@ You can use my [Tinke branch](https://github.com/priverop/tinke/tree/feat/jus_dt
 Example: `Commu/commu_pack.aar -> leader00.dtx`
 
 - Palette offset: 0x264
-- Tile offset: 0x304 
+- Tile offset: 0x304
 
 ### DTX 03
 
@@ -68,33 +69,34 @@ Offsets are relative to position 0xA (10). Absolute address = 0xA + offset.
 | short       | Tile index    |
 | signed byte | X Position    |
 | signed byte | Y Position    |
-| byte        | Shape*        |
+| byte        | Shape\*       |
 | byte        | Palette index |
 
-*More info at the bottom of the document.
+\*More info at the bottom of the document.
 
 ### Image Types (DTX03)
 
 DTX03 supports two image modes based on the swizzling:
+
 - **Tiled ("sp")**: Regular sprites compatible with Texim's sprite system. The base DSIG is tiled.
 - **Linear ("tx")**: Textures stored as sprites. The base DSIG is linear.
 
 #### Linear Sprite Workflow
 
-1. Cut segments from the DSIG image using tile index and size (shape*).
+1. Cut segments from the DSIG image using tile index and size (shape\*).
 2. Paste segments into a new empty image to compose the sprite using the coordinates (starting from the center of the image).
 
 To import them back, we use a .yaml file with all the sprite & segment info in case we want to modify them.
 
-*More info at the bottom of the document.
+\*More info at the bottom of the document.
 
 #### TileIndex
 
 The Tile Index indicates the tile of the image (DSIG) where the segment starts. The image is divided into a grid of 8x8 pixel tiles, numbered sequentially from left to right, top to bottom.
 
-Our DSIG images are usually 256 pixels wide, so each row contains 32 tiles (256 / 8 = 32). 
+Our DSIG images are usually 256 pixels wide, so each row contains 32 tiles (256 / 8 = 32).
 
-##### Example: Tile Index 65 
+##### Example: Tile Index 65
 
 - Row: 65 ÷ 32 = 2 (third row, zero-based).
 - Column: 65 % 32 = 1 (second column, zero-based).
@@ -109,7 +111,7 @@ The tile coordinates are (8, 16) to (15, 23).
 
 ### DTX 04 - Komas
 
-See [Koma Specification](Koma-Specification.md) for more details.
+See [the Koma specification](./koma.md) for more details.
 
 | Offset | Type    | Description                                             |
 | ------ | ------- | ------------------------------------------------------- |
@@ -133,6 +135,7 @@ However, this format uses the Sprite info from the KSHape file, we don't know wh
 ## Shape Property
 
 The **Shape** byte encodes both segment size and flip transformations:
+
 - **Lower 4 bits (shape & 0x0F):** Segment size (width and height).
 - **Upper 4 bits (shape >> 4):** Flip transformations.
 

docs/dev/Koma-Specification.md → docs/articles/specs/koma.md

@@ -1,6 +1,6 @@
 # Koma sprites
 
-To export all the info from the images, we need to follow some steps detailed [here](./Koma-research.md)
+To export all the info from the images, we need to follow some steps detailed [here](./koma-research.md)
 
 ## DSTX04
 

docs/articles/specs/summary.md

@@ -0,0 +1,110 @@
+# Game format specifications
+
+This section list the game assets and their format. You can find more
+information about the specification in each sub-page.
+
+## Containers
+
+Most of the assets are packed with the [`ALAR` container format](./alar.md).
+
+Some individual files are furthermore compressed with the `DSCP` format.
+
+## Texts
+
+The game doesn't have a standard format to store text. It's usually included in
+data structures, stored in files with `.bin` extension. Typically, we have
+pointers and sentences, but each file is different, that's why we have a format
+for each type of file. The [text specification](./texts.md) have more details.
+
+- `battle/tutorial*.bin`: battle tutorial text
+- `bin/ability_t.bin`: abilities
+- `bin/bgm.bin`: battle background music
+- `bin/chr_b_t.bin`: battle character abilities
+- `bin/chr_s_t.bin`: support character abilities
+- `bin/clearlst.bin`: stage goals
+- `bin/commwin.bin`: common window messages
+- `bin/demo.bin`: world names in demo player menu
+- `bin/InfoDeck.aar/*`: koma explanation in gallery menu
+- `bin/infoname.bin`: main menu helper names
+- `bin/komatxt.bin`: koma names
+- `bin/location.bin`: player location
+- `bin/piece.bin`: manga author and info
+- `bin/pname.bin`: player name titles
+- `bin/rulemess.bin` stage rules
+- `bin/stage.bin` stage names
+- `bin/title.bin` manga names
+- `deck/Deck.aar/*/*`: deck texts
+- `deckmake/tutorial.bin`: deck tutorials
+- `ending/ending.aar/ending/StaffRoll.bin`: TBD
+- `ending/ending.aar/ending/TitleOrder.bin`: TBD
+- `jgalaxy/jgalaxy.aar/jgalaxy/battle.bin`: JGalaxy battle texts
+- `jgalaxy/jgalaxy.aar/jgalaxy/jgalaxy.bin`: JGalaxy texts
+- `jgalaxy/jgalaxy.aar/jgalaxy/mission.bin`: JGalaxy mission texts
+- `jquiz/jquiz_pack.aar/jquiz/jquiz.bin`: quiz questions
+
+## Fonts
+
+The fonts are in the `font` folder with `ALFT` format.
+
+- `font/DSFont.aft`
+- `font/js8font.aft`
+- `font/jskfont_q.aft`
+- `font/jskfont.aft`
+
+## Graphics
+
+The main formats for images are:
+
+- [`DSTX`](./dtx.md): textures
+  - `ALMT`: tile map
+- `DSIG`: indexed image
+  - `ALTM`: tile map
+  - `ALOD`: unknown.
+- `NCCL`: palette
+
+Additionally, _komas_ have their own format documented in the
+[koma specification](./koma.md).
+
+## Sounds
+
+- `sound/JS2_sound.sdat`: standard Nitro `SDAT` container and sound formats.
+
+## Videos
+
+The video codec is `VXDS` from Mobiclip. This codec was a previous version to
+`MODS`. There are no known documentation or tools for this format.
+
+- `opening/opening.vx`
+
+## Data structures
+
+These files have different data structures to support different game features.
+
+- `bin/ability.bin`
+- `bin/chr_b.bin`
+- `bin/chr_s.bin`
+- `bin/clear.bin`
+- `bin/exadd.bin`
+- `bin/jpower.bin`
+- `bin/secret.bin`
+- `bin/state.bin`
+- `ChildRom/`: download-play transferable ROM and icon
+- `chr/ChrBin.aar/chr/ai/ai_param.bin`
+- `chr/ChrBin.aar/chr/ai/*` (`AIPM`)
+- `chr/ChrBin.aar/chr/ai/move/*` (`AIMV`)
+- `chr/ChrBin.aar/chr/col/*`
+- `chr/ChrBin.aar/chr/effect/*`
+- `chr/ChrBin.aar/chr/shot/*`
+- `demo/demo.aar/demo/*.mdf`
+- `dwc/utility.bin`: assets for the online communication
+- `item/item.aar/item/itemprob.ipf`
+- `jgalaxy/jgalaxy.aar/jgalaxy/*.bin` (except the one in text)
+- `opening/opening.aar/opening/star.bin`
+- `opening/PassMark.bin`
+- `opening/pattern.bin`
+- `stage/stage.aar/stage/*.bin`
+- `stage/stage.aar/stage/*.cam`
+- `stage/stage.aar/stage/*.mob`
+- `stage/stage.aar/stage/SuddenDeath.bin`
+- `title/title.aar/title/*.bin`
+- `topmenu/topmenu.aar/topmenu/*.bin`