From b34b0342f7e0b5f804543f9a4312a2524f8d43f9 Mon Sep 17 00:00:00 2001 From: Benito Palacios Sanchez Date: Thu, 23 Apr 2026 10:01:15 +0200 Subject: [PATCH 1/5] ci: fix CI running always base mode --- .github/workflows/build-and-release.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build-and-release.yml b/.github/workflows/build-and-release.yml index 3dbabbf..049828a 100644 --- a/.github/workflows/build-and-release.yml +++ b/.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 From 617d4d9231bd00cff1e6f24fc50d01c08efdd874 Mon Sep 17 00:00:00 2001 From: Benito Palacios Sanchez Date: Thu, 23 Apr 2026 10:29:39 +0200 Subject: [PATCH 2/5] doc: new doc layout --- .gitignore | 8 -- .prettierrc.yaml | 4 + .vscode/ltex.dictionary.en-US.txt | 1 + .vscode/settings.json | 3 + README.md | 28 +++--- docs/.gitignore | 12 +++ docs/api/.gitignore | 5 + .../Changelog.md => articles/changelog.md} | 0 docs/articles/dev/toc.yml | 7 ++ docs/{dev => articles/specs}/FileFormats.md | 0 .../specs/alar.md} | 0 .../specs/dtx.md} | 27 ++--- .../specs/images}/ability_t.png | Bin .../formats => articles/specs/images}/bgm.png | Bin .../specs/images}/chr_b_t.png | Bin .../specs/images}/chr_s_t.png | Bin .../specs/images}/commwin.png | Bin .../specs/images}/demo.png | Bin .../specs/images}/infoname.png | Bin .../specs/images}/komatxt.png | Bin .../specs/images}/location.png | Bin .../specs/images}/piece.png | Bin .../specs/images}/pname.png | Bin .../specs/images}/rulemess.png | Bin .../specs/images}/title.png | Bin .../specs/koma-research.md} | 0 .../specs/koma.md} | 2 +- .../specs/resources}/dig.hexpat | 0 .../specs/resources}/dtx.hexpat | 0 .../specs/resources}/filetree.txt | 0 .../specs/resources}/jus_formats.csv | Bin .../specs/resources}/komabin.hexpat | 0 .../specs/resources}/kshape.hexpat | 0 docs/articles/specs/summary.md | 82 +++++++++++++++ .../specs/texts.md} | 93 +++++++----------- docs/articles/specs/toc.yml | 61 ++++++++++++ docs/articles/tool/install.md | 51 ++++++++++ docs/articles/tool/toc.yml | 7 ++ docs/dev/toc.yml | 4 - docs/docfx.json | 17 ++-- docs/index.md | 43 +++++++- docs/toc.yml | 13 ++- src/JUS.CLI/JUS.CLI.csproj | 2 +- .../JUS.SceneGatePlugin.csproj | 4 + src/JUS.Tool/JUS.Tool.csproj | 2 +- 45 files changed, 360 insertions(+), 116 deletions(-) create mode 100644 .prettierrc.yaml create mode 100644 .vscode/ltex.dictionary.en-US.txt create mode 100644 docs/.gitignore create mode 100644 docs/api/.gitignore rename docs/{dev/Changelog.md => articles/changelog.md} (100%) create mode 100644 docs/articles/dev/toc.yml rename docs/{dev => articles/specs}/FileFormats.md (100%) rename docs/{dev/Alar-Specification.md => articles/specs/alar.md} (100%) rename docs/{dev/DTX-Specification.md => articles/specs/dtx.md} (90%) rename docs/{images/formats => articles/specs/images}/ability_t.png (100%) rename docs/{images/formats => articles/specs/images}/bgm.png (100%) rename docs/{images/formats => articles/specs/images}/chr_b_t.png (100%) rename docs/{images/formats => articles/specs/images}/chr_s_t.png (100%) rename docs/{images/formats => articles/specs/images}/commwin.png (100%) rename docs/{images/formats => articles/specs/images}/demo.png (100%) rename docs/{images/formats => articles/specs/images}/infoname.png (100%) rename docs/{images/formats => articles/specs/images}/komatxt.png (100%) rename docs/{images/formats => articles/specs/images}/location.png (100%) rename docs/{images/formats => articles/specs/images}/piece.png (100%) rename docs/{images/formats => articles/specs/images}/pname.png (100%) rename docs/{images/formats => articles/specs/images}/rulemess.png (100%) rename docs/{images/formats => articles/specs/images}/title.png (100%) rename docs/{dev/Koma-research.md => articles/specs/koma-research.md} (100%) rename docs/{dev/Koma-Specification.md => articles/specs/koma.md} (99%) rename docs/{dev/hexpat => articles/specs/resources}/dig.hexpat (100%) rename docs/{dev => articles/specs/resources}/dtx.hexpat (100%) rename docs/{ => articles/specs/resources}/filetree.txt (100%) rename docs/{ => articles/specs/resources}/jus_formats.csv (100%) rename docs/{dev => articles/specs/resources}/komabin.hexpat (100%) rename docs/{dev => articles/specs/resources}/kshape.hexpat (100%) create mode 100644 docs/articles/specs/summary.md rename docs/{dev/Text-Specification.md => articles/specs/texts.md} (76%) create mode 100644 docs/articles/specs/toc.yml create mode 100644 docs/articles/tool/install.md create mode 100644 docs/articles/tool/toc.yml delete mode 100644 docs/dev/toc.yml diff --git a/.gitignore b/.gitignore index 008a4a7..6e22c5c 100644 --- a/.gitignore +++ b/.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 diff --git a/.prettierrc.yaml b/.prettierrc.yaml new file mode 100644 index 0000000..ec3b3e2 --- /dev/null +++ b/.prettierrc.yaml @@ -0,0 +1,4 @@ +overrides: + - files: "*.md" + options: + proseWrap: always diff --git a/.vscode/ltex.dictionary.en-US.txt b/.vscode/ltex.dictionary.en-US.txt new file mode 100644 index 0000000..5b31bb5 --- /dev/null +++ b/.vscode/ltex.dictionary.en-US.txt @@ -0,0 +1 @@ +koma diff --git a/.vscode/settings.json b/.vscode/settings.json index 577e608..644cb16 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -13,4 +13,7 @@ "editor.formatOnType": true }, "prettier.proseWrap": "always", + "cSpell.words": [ + "Koma" + ], } \ No newline at end of file diff --git a/README.md b/README.md index aa06bd7..f0e9a0f 100644 --- a/README.md +++ b/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. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..83cc63a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,12 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ +_site + +# DrawIO +.$*.drawio* diff --git a/docs/api/.gitignore b/docs/api/.gitignore new file mode 100644 index 0000000..7e7bb37 --- /dev/null +++ b/docs/api/.gitignore @@ -0,0 +1,5 @@ +############### +# temp file # +############### +*.yml +.manifest \ No newline at end of file diff --git a/docs/dev/Changelog.md b/docs/articles/changelog.md similarity index 100% rename from docs/dev/Changelog.md rename to docs/articles/changelog.md diff --git a/docs/articles/dev/toc.yml b/docs/articles/dev/toc.yml new file mode 100644 index 0000000..b2f54d0 --- /dev/null +++ b/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 diff --git a/docs/dev/FileFormats.md b/docs/articles/specs/FileFormats.md similarity index 100% rename from docs/dev/FileFormats.md rename to docs/articles/specs/FileFormats.md diff --git a/docs/dev/Alar-Specification.md b/docs/articles/specs/alar.md similarity index 100% rename from docs/dev/Alar-Specification.md rename to docs/articles/specs/alar.md diff --git a/docs/dev/DTX-Specification.md b/docs/articles/specs/dtx.md similarity index 90% rename from docs/dev/DTX-Specification.md rename to docs/articles/specs/dtx.md index cbca57f..0051f9c 100644 --- a/docs/dev/DTX-Specification.md +++ b/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. diff --git a/docs/images/formats/ability_t.png b/docs/articles/specs/images/ability_t.png similarity index 100% rename from docs/images/formats/ability_t.png rename to docs/articles/specs/images/ability_t.png diff --git a/docs/images/formats/bgm.png b/docs/articles/specs/images/bgm.png similarity index 100% rename from docs/images/formats/bgm.png rename to docs/articles/specs/images/bgm.png diff --git a/docs/images/formats/chr_b_t.png b/docs/articles/specs/images/chr_b_t.png similarity index 100% rename from docs/images/formats/chr_b_t.png rename to docs/articles/specs/images/chr_b_t.png diff --git a/docs/images/formats/chr_s_t.png b/docs/articles/specs/images/chr_s_t.png similarity index 100% rename from docs/images/formats/chr_s_t.png rename to docs/articles/specs/images/chr_s_t.png diff --git a/docs/images/formats/commwin.png b/docs/articles/specs/images/commwin.png similarity index 100% rename from docs/images/formats/commwin.png rename to docs/articles/specs/images/commwin.png diff --git a/docs/images/formats/demo.png b/docs/articles/specs/images/demo.png similarity index 100% rename from docs/images/formats/demo.png rename to docs/articles/specs/images/demo.png diff --git a/docs/images/formats/infoname.png b/docs/articles/specs/images/infoname.png similarity index 100% rename from docs/images/formats/infoname.png rename to docs/articles/specs/images/infoname.png diff --git a/docs/images/formats/komatxt.png b/docs/articles/specs/images/komatxt.png similarity index 100% rename from docs/images/formats/komatxt.png rename to docs/articles/specs/images/komatxt.png diff --git a/docs/images/formats/location.png b/docs/articles/specs/images/location.png similarity index 100% rename from docs/images/formats/location.png rename to docs/articles/specs/images/location.png diff --git a/docs/images/formats/piece.png b/docs/articles/specs/images/piece.png similarity index 100% rename from docs/images/formats/piece.png rename to docs/articles/specs/images/piece.png diff --git a/docs/images/formats/pname.png b/docs/articles/specs/images/pname.png similarity index 100% rename from docs/images/formats/pname.png rename to docs/articles/specs/images/pname.png diff --git a/docs/images/formats/rulemess.png b/docs/articles/specs/images/rulemess.png similarity index 100% rename from docs/images/formats/rulemess.png rename to docs/articles/specs/images/rulemess.png diff --git a/docs/images/formats/title.png b/docs/articles/specs/images/title.png similarity index 100% rename from docs/images/formats/title.png rename to docs/articles/specs/images/title.png diff --git a/docs/dev/Koma-research.md b/docs/articles/specs/koma-research.md similarity index 100% rename from docs/dev/Koma-research.md rename to docs/articles/specs/koma-research.md diff --git a/docs/dev/Koma-Specification.md b/docs/articles/specs/koma.md similarity index 99% rename from docs/dev/Koma-Specification.md rename to docs/articles/specs/koma.md index c2393a1..f368591 100644 --- a/docs/dev/Koma-Specification.md +++ b/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 diff --git a/docs/dev/hexpat/dig.hexpat b/docs/articles/specs/resources/dig.hexpat similarity index 100% rename from docs/dev/hexpat/dig.hexpat rename to docs/articles/specs/resources/dig.hexpat diff --git a/docs/dev/dtx.hexpat b/docs/articles/specs/resources/dtx.hexpat similarity index 100% rename from docs/dev/dtx.hexpat rename to docs/articles/specs/resources/dtx.hexpat diff --git a/docs/filetree.txt b/docs/articles/specs/resources/filetree.txt similarity index 100% rename from docs/filetree.txt rename to docs/articles/specs/resources/filetree.txt diff --git a/docs/jus_formats.csv b/docs/articles/specs/resources/jus_formats.csv similarity index 100% rename from docs/jus_formats.csv rename to docs/articles/specs/resources/jus_formats.csv diff --git a/docs/dev/komabin.hexpat b/docs/articles/specs/resources/komabin.hexpat similarity index 100% rename from docs/dev/komabin.hexpat rename to docs/articles/specs/resources/komabin.hexpat diff --git a/docs/dev/kshape.hexpat b/docs/articles/specs/resources/kshape.hexpat similarity index 100% rename from docs/dev/kshape.hexpat rename to docs/articles/specs/resources/kshape.hexpat diff --git a/docs/articles/specs/summary.md b/docs/articles/specs/summary.md new file mode 100644 index 0000000..7b5093a --- /dev/null +++ b/docs/articles/specs/summary.md @@ -0,0 +1,82 @@ +# 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 +- `jgalaxy/jgalaxy.aar/*`: JGalaxy texts +- `jquiz/jquiz.aar/`: quiz questions + +## Fonts + +Pending documentation. + +## Graphics + +The main formats for images are: + +- [`DSTX`](./dtx.md) +- `DSIG` + +Additionally, _komas_ have their own format documented in the +[koma specification](./koma.md). + +## Sound + +- `sound/JS2_sound.sdat`: standard Nitro `SDAT` container and sound formats. + +## Data structures + +These files have different data structures to support the 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. +- `dwc/utility.bin`: assets for the online communication. +- `opening/PassMark.bin` +- `opening/pattern.bin` + +## General info + +### Absolute pointers + +Absolute pointers mean that the text is in the pointer offset plus the position +of the pointer. If the position of the pointer is 0x04 and the value is 0x100, +the text will be in 0x104. diff --git a/docs/dev/Text-Specification.md b/docs/articles/specs/texts.md similarity index 76% rename from docs/dev/Text-Specification.md rename to docs/articles/specs/texts.md index bd626ce..9a93d15 100644 --- a/docs/dev/Text-Specification.md +++ b/docs/articles/specs/texts.md @@ -1,15 +1,5 @@ # Text files -In this game the texts are stored in .bin files. Usually we have pointers and -sentences, but each file is different, that's why we have a format for each type -of file. - -## Absolute pointers - -Absolute pointers means that the text is in the pointer offset plus the position -of the pointer. If the position of the pointer is 0x04 and the value is 0x100, -the text will be in 0x104. - ## Utility classes To help with the process we've developed some classes to read and write easily: @@ -25,43 +15,34 @@ To help with the process we've developed some classes to read and write easily: ## Battle folder Here we have the tutorials. **Relative Pointers**. They all have the same -structure: _StartingOffset_, a lot of random unknown ints and the pointers. +structure: _StartingOffset_, a lot of random unknown integers and the pointers. These pointers just store the size of the string starting from 0. For example if -the first two strings are 2bytes and 4bytes long, the pointers will be 02 and +the first two strings are 2 bytes and 4 bytes long, the pointers will be 02 and then 06. We store the unused pointers in the Po file as comments. -| Name | Format | -| ------------- | -------------- | -| tutorial0.bin | BattleTutorial | -| tutorial1.bin | BattleTutorial | -| tutorial2.bin | BattleTutorial | -| tutorial3.bin | BattleTutorial | -| tutorial4.bin | BattleTutorial | -| tutorial5.bin | BattleTutorial | - ## Bin folder The Format class has the main properties of the file and a list of Entries. -| Image | Name | Format | Location | -| ------------------------------------------------- | ------------- | ------------------------ | --------------------------------------------------- | -| ![ability_t.bin](../images/formats/ability_t.png) | ability_t.bin | Ability + AbilityEntry | Koma list, helper (koma size 1) ability description | -| ![bgm.bin](../images/formats/bgm.png) | bgm.bin | Bgm + BgmEntry | Battle stage Background Music (Database menu) | -| ![chr_b_t.bin](../images/formats/chr_b_t.png) | chr_b_t.bin | BtlChr + BtlChrEntry | Koma abilities info | -| ![chr_s_t.bin](../images/formats/chr_s_t.png) | chr_s_t.bin | SuppChr + SuppChrEntry | Koma abilities info support komas | -| ![clearlst.bin](../images/formats/clearlst.png) | clearlst.bin | SimpleBin | Stage goals | -| ![commwin.bin](../images/formats/commwin.png) | commwin.bin | Commwin + CommwinEntry | Common window messages | -| ![demo.bin](../images/formats/demo.png) | demo.bin | Demo + DemoEntry | World names (demo player menu, database) | -| ![infoname.bin](../images/formats/infoname.png) | infoname.bin | SimpleBin | Main menu helper names | -| ![komatxt.bin](../images/formats/komatxt.png) | komatxt.bin | Komatxt + KomatxtEntry | Koma names | -| ![location.bin](../images/formats/location.png) | location.bin | Location + LocationEntry | Player location | -| ![piece.bin](../images/formats/piece.png) | piece.bin | Piece + PieceEntry | Manga author and info (database menu) | -| ![pname.bin](../images/formats/pname.png) | pname.bin | Pname | Player name titles (player settings) | -| ![rulemess.bin](../images/formats/rulemess.png) | rulemess.bin | Rulemess + RulemessEntry | Stage rules | -| ![stage.bin](../images/formats/stage.png) | stage.bin | Stage + StageEntry | Stage names | -| ![title.bin](../images/formats/title.png) | title.bin | SimpleBin | Manga names | +| Image | Name | Format | Location | +| ---------------------------------------- | ------------- | ------------------------ | --------------------------------------------------- | +| ![ability_t.bin](./images/ability_t.png) | ability_t.bin | Ability + AbilityEntry | Koma list, helper (koma size 1) ability description | +| ![bgm.bin](./images/bgm.png) | bgm.bin | Bgm + BgmEntry | Battle stage Background Music (Database menu) | +| ![chr_b_t.bin](./images/chr_b_t.png) | chr_b_t.bin | BtlChr + BtlChrEntry | Koma abilities info | +| ![chr_s_t.bin](./images/chr_s_t.png) | chr_s_t.bin | SuppChr + SuppChrEntry | Koma abilities info support komas | +| clearlst.bin | clearlst.bin | SimpleBin | Stage goals | +| ![commwin.bin](./images/commwin.png) | commwin.bin | Commwin + CommwinEntry | Common window messages | +| ![demo.bin](./images/demo.png) | demo.bin | Demo + DemoEntry | World names (demo player menu, database) | +| ![infoname.bin](./images/infoname.png) | infoname.bin | SimpleBin | Main menu helper names | +| ![komatxt.bin](./images/komatxt.png) | komatxt.bin | Komatxt + KomatxtEntry | Koma names | +| ![location.bin](./images/location.png) | location.bin | Location + LocationEntry | Player location | +| ![piece.bin](./images/piece.png) | piece.bin | Piece + PieceEntry | Manga author and info (database menu) | +| ![pname.bin](./images/pname.png) | pname.bin | Pname | Player name titles (player settings) | +| ![rulemess.bin](./images/rulemess.png) | rulemess.bin | Rulemess + RulemessEntry | Stage rules | +| stage.bin | stage.bin | Stage + StageEntry | Stage names | +| ![title.bin](./images/title.png) | title.bin | SimpleBin | Manga names | ### Formats @@ -154,8 +135,9 @@ some of them includes also p-files (a p and then the 3 digit numbers). ## InfoDeck folder -Deck are the explanation of the komas in the Gallery menu (9 visible lines and 1 invisible = 10 lines per page). Each line is 40 character long. - +Deck are the explanation of the komas in the Gallery menu (9 visible lines and 1 +invisible = 10 lines per page). Each line is 40 character long. + Info are the helper dialogs. Just simple strings. Starting offset + absolute pointers + just strings. @@ -280,7 +262,8 @@ This format is pretty simple. So the size of the file is 4 + (164 \* number_of_entries). -Each entry has the text (description), then a lot of 00s and at the end an unknown number of bytes (unknown region). +Each entry has the text (description), then a lot of 00s and at the end an +unknown number of bytes (unknown region). ### JGalaxyComplex @@ -336,22 +319,18 @@ Starting Offset: 0x0001D5B4 (120244) where the text starts. Offset of the empty string: 0x1D5B4 (120244). ### Pointers Entry 1 -| Offset | Type | Pointer | Text Length* | Pointer Calc (Offset + Pointer) | -| ------ | ---------- | ------------------- | ------------ | ------------------------------- | -| 0x4 | MangaID | | 1 | | -| 0x8 | Photo | 120236(0x01 D5 AC) | 0 | 120244 (0x01 D5 B4) | -| 0xC | Question 1 | 120233 (0x01 D5 A9) | 30 | 120245 (0x01 D5 B5) | -| 0x10 | Question 2 | 120260 (0x01 D5 C4) | 14 | 120276 (0x01 D5 D4) | -| 0x14 | Question 3 | 120224 (0x01 D5 A0) | 0 | 120244 (0x01 D5 B4) | -| 0x18 | Question 4 | 120220 (0x01 D5 9C) | 0 | 120244 (0x01 D5 B4) | - -*No null byte. -> [!CAUTION] -> This file has two random `81 40 00`, maybe it means something in the game graphics but I don't know yet. +| Offset | Type | Pointer | Text Length\* | Pointer Calc (Offset + Pointer) | +| ------ | ---------- | ------------------- | ------------- | ------------------------------- | +| 0x4 | MangaID | | 1 | | +| 0x8 | Photo | 120236(0x01 D5 AC) | 0 | 120244 (0x01 D5 B4) | +| 0xC | Question 1 | 120233 (0x01 D5 A9) | 30 | 120245 (0x01 D5 B5) | +| 0x10 | Question 2 | 120260 (0x01 D5 C4) | 14 | 120276 (0x01 D5 D4) | +| 0x14 | Question 3 | 120224 (0x01 D5 A0) | 0 | 120244 (0x01 D5 B4) | +| 0x18 | Question 4 | 120220 (0x01 D5 9C) | 0 | 120244 (0x01 D5 B4) | -## Bin files without text +\*No null byte. -- dwc/utility.bin -- opening/PassMark.bin -- pattern.bin +> [!CAUTION] +> This file has two random `81 40 00`, maybe it means something in the game +> graphics but I don't know yet. diff --git a/docs/articles/specs/toc.yml b/docs/articles/specs/toc.yml new file mode 100644 index 0000000..86045b0 --- /dev/null +++ b/docs/articles/specs/toc.yml @@ -0,0 +1,61 @@ +- name: 👊 Jump Ultimate Stars formats +- name: Overview + href: ./summary.md + +- name: 📁 Containers +- name: AAR / ALAR + href: alar.md +#- name: TODO: DSCP +# href: dscp.md + +- name: 🖼️ Graphics +- name: DTX sprites + href: dtx.md +- name: Koma sprites + href: koma.md + +#- name: 🈂️ Fonts +#- name: TODO: ALFT +# href: alft.md + +- name: 📝 Texts +- name: Battle tutorial + href: texts.md +- name: Abilities + href: texts.md +- name: Music titles + href: texts.md +- name: Characters + href: texts.md +- name: Stage clear messages + href: texts.md +- name: Window messages + href: texts.md +- name: Introduction + href: texts.md +- name: Deck info + href: texts.md +- name: Deck + href: texts.md +- name: Info names + href: texts.md +- name: Koma texts + href: texts.md +- name: Pieces + href: texts.md +- name: Names + href: texts.md +- name: Location + href: texts.md +- name: Rules + href: texts.md +- name: Stage + href: texts.md +- name: Title + href: texts.md +- name: Tutorial + href: texts.md +- name: JGalaxy + href: texts.md +- name: JQuiz + href: texts.md diff --git a/docs/articles/tool/install.md b/docs/articles/tool/install.md new file mode 100644 index 0000000..9814bab --- /dev/null +++ b/docs/articles/tool/install.md @@ -0,0 +1,51 @@ +# JUSToolkit: Installation + +**JUS.CLI** is the main application of the project. It's a console application +(no graphical interface). + +## Prerequisites + +The utility requires the +[.NET 10.0 runtime](https://dotnet.microsoft.com/en-us/download/dotnet/10.0). +You can verify the installation by running `dotnet --list-runtimes` from a +terminal. If it says `Microsoft.NETCore.App` 10.0 or higher is installed, it +should be fine. + +## Installation + +Download the latest stable version from the +[release page](https://github.com/priverop/JUSToolkit/releases) of the project. + +Preview versions can be downloaded from the project +[_Actions pipeline artifacts_](https://github.com/priverop/JUSToolkit/actions/workflows/build-and-release.yml). +But they expire after a few days. You may want to follow the +[source code README file](https://github.com/priverop/JUSToolkit) to build the +latest version yourself. + +## How to use + +`./JUS.CLI jus [type] [feature] [args]` + +- graphics + - export-dtx + - export-dig + - import-dig +- containers + - export-alar3 + - import-alar3 + - export-alar2 + - import-alar2 + - import + - export +- batch + - export-alar-png + - import-png-alar3 +- game + - import + +To get the arguments of a feature you can use: +`./JUS.CLI jus [type] [feature] -h` + +Examples: +`./JUS.CLI jus containers export-alar3 --container test.aar --output myDirectory` +`./JUS.CLI jus containers export-alar3 -h` diff --git a/docs/articles/tool/toc.yml b/docs/articles/tool/toc.yml new file mode 100644 index 0000000..7f71251 --- /dev/null +++ b/docs/articles/tool/toc.yml @@ -0,0 +1,7 @@ +- name: ✨ Getting started +- name: Introduction + href: ../../index.md + +- name: 🛠️ JUSToolkit console +- name: Installation + href: install.md diff --git a/docs/dev/toc.yml b/docs/dev/toc.yml deleted file mode 100644 index 56496ea..0000000 --- a/docs/dev/toc.yml +++ /dev/null @@ -1,4 +0,0 @@ -- name: Changelog - href: Changelog.md -- name: API - href: ../api/toc.yml diff --git a/docs/docfx.json b/docs/docfx.json index 40a546c..82d0102 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -23,18 +23,13 @@ "build": { "content": [ { - "files": [ "api/**.yml", "api/index.md", "dev/**" ] + "files": [ + "api/**.yml", + "api/index.md" + ] }, - { - "files": [ "toc.yml", "index.md" ] - }, - { - "files": [ "guides/**" ] - }, - { - "files": ["README.md", "CONTRIBUTING.md"], - "src": "../" - } + { "files": "**/*.{md,yml}", "src": "articles", "dest": "docs" }, + { "files": [ "toc.yml", "*.md" ] } ], "resource": [ { diff --git a/docs/index.md b/docs/index.md index d1950d1..5f027e5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,40 @@ ---- -uid: README ---- +# JUSToolkit -[!include[README](../README.md)] +Romhacking tools for Jump Ultimate Stars! (NDS) +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://choosealicense.com/licenses/mit/) + +## Features + +Done ✔️ To test / with issues ⚠️ Not done 🛑 + +### Containers + +- Pack .aar ALAR3 ✔️ +- Unpack .aar ALAR3 ✔️ +- Pack .aar ALAR2 ✔️ +- Unpack .aar ALAR2 ✔️ + +### Graphics + +- Extract ALMT + DIG ✔️ +- Import ALMT + DIG ✔️ +- Extract DTX ✔️ +- Import DTX 🛑 + +### Texts + +- Extract and import ✔️ + +### Batch Features + +- Extract every .dig from any .aar (ALAR2/ALAR3) to PNG ✔️ +- Import multiple PNGs to an .aar ALAR3 container ✔️ + +## Credits + +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. diff --git a/docs/toc.yml b/docs/toc.yml index 4f9f713..a0f134e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -1,8 +1,11 @@ -- name: Home - href: index.md +- name: Tool + href: articles/tool/ -- name: Format Specifications - href: dev/ +- name: Format specs + href: articles/specs/ -- name: GitHub +- name: Dev guides + href: articles/dev/ + +- name: Source code href: https://github.com/priverop/JUSToolkit diff --git a/src/JUS.CLI/JUS.CLI.csproj b/src/JUS.CLI/JUS.CLI.csproj index 6200e3f..8b7152c 100644 --- a/src/JUS.CLI/JUS.CLI.csproj +++ b/src/JUS.CLI/JUS.CLI.csproj @@ -8,7 +8,7 @@ - + diff --git a/src/JUS.SceneGatePlugin/JUS.SceneGatePlugin.csproj b/src/JUS.SceneGatePlugin/JUS.SceneGatePlugin.csproj index 3984ea7..89af50b 100644 --- a/src/JUS.SceneGatePlugin/JUS.SceneGatePlugin.csproj +++ b/src/JUS.SceneGatePlugin/JUS.SceneGatePlugin.csproj @@ -10,6 +10,10 @@ false + + + + diff --git a/src/JUS.Tool/JUS.Tool.csproj b/src/JUS.Tool/JUS.Tool.csproj index 7f2775f..63c747c 100644 --- a/src/JUS.Tool/JUS.Tool.csproj +++ b/src/JUS.Tool/JUS.Tool.csproj @@ -8,7 +8,7 @@ - + From f1edb1fdd1cb7330b6eae57a556a96a142bb0c3f Mon Sep 17 00:00:00 2001 From: Benito Palacios Sanchez Date: Thu, 23 Apr 2026 10:38:41 +0200 Subject: [PATCH 3/5] doc: revert unfinished changes --- docs/articles/specs/summary.md | 8 -------- docs/articles/specs/texts.md | 19 +++++++++++++++++++ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/articles/specs/summary.md b/docs/articles/specs/summary.md index 7b5093a..9052b2a 100644 --- a/docs/articles/specs/summary.md +++ b/docs/articles/specs/summary.md @@ -72,11 +72,3 @@ These files have different data structures to support the game features. - `dwc/utility.bin`: assets for the online communication. - `opening/PassMark.bin` - `opening/pattern.bin` - -## General info - -### Absolute pointers - -Absolute pointers mean that the text is in the pointer offset plus the position -of the pointer. If the position of the pointer is 0x04 and the value is 0x100, -the text will be in 0x104. diff --git a/docs/articles/specs/texts.md b/docs/articles/specs/texts.md index 9a93d15..0fdb0e9 100644 --- a/docs/articles/specs/texts.md +++ b/docs/articles/specs/texts.md @@ -1,5 +1,15 @@ # Text files +In this game the texts are stored in .bin files. Usually we have pointers and +sentences, but each file is different, that's why we have a format for each type +of file. + +## Absolute pointers + +Absolute pointers mean that the text is in the pointer offset plus the position +of the pointer. If the position of the pointer is 0x04 and the value is 0x100, +the text will be in 0x104. + ## Utility classes To help with the process we've developed some classes to read and write easily: @@ -22,6 +32,15 @@ then 06. We store the unused pointers in the Po file as comments. +| Name | Format | +| ------------- | -------------- | +| tutorial0.bin | BattleTutorial | +| tutorial1.bin | BattleTutorial | +| tutorial2.bin | BattleTutorial | +| tutorial3.bin | BattleTutorial | +| tutorial4.bin | BattleTutorial | +| tutorial5.bin | BattleTutorial | + ## Bin folder The Format class has the main properties of the file and a list of Entries. From 2675411954a6d87529e0a95f41502957a4a69ffe Mon Sep 17 00:00:00 2001 From: Benito Palacios Sanchez Date: Thu, 23 Apr 2026 11:44:33 +0200 Subject: [PATCH 4/5] docs: add more binary formats --- docs/articles/specs/summary.md | 54 ++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/articles/specs/summary.md b/docs/articles/specs/summary.md index 9052b2a..f685fe3 100644 --- a/docs/articles/specs/summary.md +++ b/docs/articles/specs/summary.md @@ -35,30 +35,50 @@ for each type of file. The [text specification](./texts.md) have more details. - `bin/title.bin` manga names - `deck/Deck.aar/*/*`: deck texts - `deckmake/tutorial.bin`: deck tutorials -- `jgalaxy/jgalaxy.aar/*`: JGalaxy texts -- `jquiz/jquiz.aar/`: quiz questions +- `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 -Pending documentation. +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) -- `DSIG` +- [`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). -## Sound +## 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 the game features. +These files have different data structures to support different game features. - `bin/ability.bin` - `bin/chr_b.bin` @@ -68,7 +88,23 @@ These files have different data structures to support the game features. - `bin/jpower.bin` - `bin/secret.bin` - `bin/state.bin` -- `ChildRom/`: download-play transferable ROM and icon. -- `dwc/utility.bin`: assets for the online communication. +- `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` From 048af30834b1dbe4fa264bdd46f70e3cefd4acfd Mon Sep 17 00:00:00 2001 From: Benito Palacios Sanchez Date: Thu, 23 Apr 2026 13:55:03 +0200 Subject: [PATCH 5/5] feat: detect compressed files in SG plugin and ALMT variant --- src/JUS.SceneGatePlugin/JusBinaryHeaderConverterMatcher.cs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/JUS.SceneGatePlugin/JusBinaryHeaderConverterMatcher.cs b/src/JUS.SceneGatePlugin/JusBinaryHeaderConverterMatcher.cs index 4b341b8..b10fd38 100644 --- a/src/JUS.SceneGatePlugin/JusBinaryHeaderConverterMatcher.cs +++ b/src/JUS.SceneGatePlugin/JusBinaryHeaderConverterMatcher.cs @@ -1,6 +1,7 @@ using System.Diagnostics.CodeAnalysis; using JUS.Tool.Containers.Converters; using JUS.Tool.Graphics.Converters; +using JUS.Tool.Utils; using SceneGate.UI.Formats.Discovery; using Yarhl.FileSystem; using Yarhl.IO; @@ -14,8 +15,10 @@ public sealed class JusBinaryHeaderConverterMatcher : IConverterMatcher // Containers HeaderFormat.Create("ALAR", 2, null), HeaderFormat.Create("ALAR", 3, null), + HeaderFormat.Create("DSCP", null, null), // Graphics HeaderFormat.Create("ALMT", null, null), + HeaderFormat.Create("ALTM", null, null), HeaderFormat.Create("DSIG", null, null), HeaderFormat.Create("DSTX", 1, 3), HeaderFormat.Create("DSTX", 1, 4),