From a98bb66acc929e37da1a54816b2083a731e287a9 Mon Sep 17 00:00:00 2001 From: etienerodri Date: Mon, 17 Aug 2026 20:10:26 -0400 Subject: [PATCH] Initialize README for PRSA Map Editor Add README.md for PRSA Map Editor with features and usage instructions. --- README.md | 469 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 469 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c04712c --- /dev/null +++ b/README.md @@ -0,0 +1,469 @@ +# PRSA Map Editor + +PRSA Map Editor is a map editing tool for **Pokémon Ranger: Shadows of Almia**. + +The goal of this tool is to make editing the game's maps easier without having to edit everything by hand in a hex editor. + +The tool can load a Shadows of Almia ROM, extract the files it needs, render the maps, let you edit different parts of the map, and save your changes back into a new ROM. + +This project is still being worked on, so some parts may change as more of the game formats are figured out. + +--- + +## Features + +### Map Viewer + +* Load a Pokémon Ranger: Shadows of Almia ROM +* Extract the ROM files needed by the editor +* Load already extracted ROM files +* Browse the maps in the game +* Render the maps using the real game graphics +* Zoom in and out +* Scroll around larger maps +* Play map animations +* Render CTA animations +* Render PLA palette animations +* Render NPC animations +* Render object animations +* Show or hide Pokémon +* Show or hide NPCs +* Show or hide objects + +--- + +## Collision Editor + +The collision editor lets you edit the map's `0x03` collision layer. + +You can: + +* See the collision grid over the map +* Paint collision values directly on the map +* Drag the mouse to paint multiple cells +* See every collision value used by the map +* Select different collision types +* Use **Color Mode** +* Use **Number Mode** +* Save the edited collision back into a new ROM + +Each collision cell is based on a **16x16 pixel** part of the map. + +Number Mode shows the collision value directly on each tile. + +For example: + +```text +0x001A +``` + +will show as: + +```text +1A +``` + +--- + +## Palette Editor + +The palette editor lets you change the colors used by the map. + +You can: + +* Select a tileset +* Select a palette bank +* Edit colors one at a time +* Use a color picker +* Enter colors using HEX +* Preview the tileset +* Import palette TXT files +* Export palette TXT files +* Change Hue +* Change Saturation +* Change Value +* Change every color in one palette bank +* Change every palette color in the map +* See palette changes on the map +* Edit colors used by PLA animations +* Keep palette changes when moving between maps +* Save changes from multiple maps into one ROM + +There are two larger palette tools: + +### Change All Palette Bank Colors + +Changes the colors inside the selected palette bank. + +### Change All Colors + +Changes all palette colors used by the map. + +--- + +## Pokémon Editor + +The Pokémon editor lets you change the Pokémon placed on a map. + +You can: + +* View Pokémon already on the map +* See their real sprites +* Move Pokémon by dragging them +* Edit their X and Y position +* Delete Pokémon +* Add Pokémon +* Browse Pokémon using the Pokémon Menu +* Search Pokémon by name +* Select multiple Pokémon from the menu +* Add multiple Pokémon at the same time +* Save Pokémon changes into a new ROM + +If a map does not already have a Pokémon layer, the editor can create the `0x09` layer when Pokémon are added. + +--- + +## Pokémon Randomizer + +The tool also has a Pokémon randomizer. + +The randomizer goes through the maps and changes Pokémon placements while trying to keep the field move requirements usable. + +The original ROM is not overwritten. + +A new randomized ROM is created instead. + +--- + +## NPC Editor + +The NPC editor lets you work with the map's `0x08` NPC layer. + +You can: + +* View NPCs on the map +* Render their real sprites +* See NPC animations +* Select NPCs +* Move NPCs by dragging them +* Edit X and Y positions +* Add NPCs +* Delete NPCs +* Set an NPC to visible +* Set an NPC to not visible +* Browse available NPCs using the NPC Menu +* Search NPCs by ID +* Select multiple NPCs +* Add multiple NPCs at once +* Save NPC changes into a new ROM + +The editor uses `fielddata.bin` when needed to match NPC records with the correct NPC graphics. + +--- + +## Object Editor + +The object editor works with the map's `0x04` object layer. + +Objects can be things like: + +* Boxes +* Signs +* Doors +* Furniture +* Map props +* Other interactive objects + +You can: + +* View objects on the map +* Render their real game graphics +* See object animations +* Move objects +* Edit X and Y positions +* Add objects +* Delete objects +* Browse objects using the Objects Menu +* Search objects by ID +* Select multiple objects +* Add multiple objects at once +* Create needed TOBJ entries in `fielddata.bin` +* Save object changes into a new ROM + +New objects are created using the correct starting state needed for them to appear on the map. + +--- + +## PNG Export + +Rendered maps can be exported as PNG images. + +The exporter uses lossless PNG and exports at a larger resolution when possible. + +This is useful for: + +* Looking at full maps +* Map research +* Comparing edits +* Making references +* Working with map graphics in image editors + +--- + +## Saving + +The editor does not overwrite your original ROM. + +When saving changes, the tool creates a new `.nds` file. + +Depending on what you edited, the tool can update things such as: + +```text +Map DAT files +Map TEX files +fielddata.bin +``` + +The files are then put back into a new ROM. + +Always keep a backup of your original ROM. + +--- + +## Requirements + +You will need: + +* Windows, Linux, or another system that can run Java +* Java 17 or newer +* A Pokémon Ranger: Shadows of Almia Nintendo DS ROM + +The ROM is **not included** with this project. + +--- + +## Running The Tool + +Download the latest `.jar` file. + +Run: + +```text +AlmiaMapEditor.jar +``` + +You can also run it from a terminal with: + +```bash +java -jar AlmiaMapEditor.jar +``` + +--- + +## Basic Use + +### 1. Start the editor + +Open the JAR. + +### 2. Select your ROM + +Press: + +```text +SELECT ROM +``` + +Choose your Pokémon Ranger: Shadows of Almia `.nds` file. + +The editor will extract the files it needs. + +### 3. Select a map + +Use the map list on the left side. + +Click a map and wait for it to render. + +Map names look like: + +```text +m001_001 +m001_007 +m002_003 +``` + +### 4. Choose what you want to edit + +Use the buttons at the top: + +```text +POKEMON +NPC +COLLISION +PALETTE +OBJECTS +``` + +### 5. Make your changes + +Edit the map using the menu you selected. + +### 6. Save + +Use the save button inside the editor you are using. + +The tool will create a new ROM with your changes. + +--- + +## Map Files + +Shadows of Almia maps mainly use files like: + +```text +m001_001.map.dat.lz +m001_001.map.tex.lz +``` + +The DAT contains the map layout and different map layers. + +The TEX contains the map graphics and palettes. + +Some of the map layers currently used by the editor are: + +```text +0x02 - Map graphics +0x03 - Collision +0x04 - Objects +0x08 - NPCs +0x09 - Pokémon +0x0D - Map graphics / shadows +0x0E - CTA animation +``` + +The game also uses other files such as: + +```text +fielddata.bin +PokeID.bin +NPC archives +Object archives +CTA files +PLA files +``` + +The editor reads these files to make the maps look and work closer to how they do in the game. + +--- + +## Extracted ROM Folder + +After selecting a ROM, the editor creates an extracted ROM folder. + +You can use: + +```text +LOAD ROM FOLDER +``` + +to load those files again without extracting the ROM another time. + +This is useful when testing the tool or working on the same ROM more than once. + +--- + +## Current Status + +The editor is still in development. + +A lot of the map format is working, but Pokémon Ranger: Shadows of Almia has many different map systems and special cases. + +Things may still be wrong on some maps. + +If you find a map that: + +* Renders wrong +* Has the wrong colors +* Has a broken animation +* Has the wrong NPC +* Has the wrong object +* Saves incorrectly + +open an issue and include the map name. + +Example: + +```text +m001_007 +``` + +Explain what is wrong and what you expected to happen. + +Screenshots are also helpful. + +--- + +## Bugs + +If the tool crashes or something does not work, open an issue. + +Please include: + +* What you were doing +* The map name +* What editor you were using +* What happened +* What you expected to happen +* A screenshot if possible + +Do **not** upload copyrighted ROM files when reporting a bug. + +--- + +## Project Goal + +The main goal is to eventually make editing Shadows of Almia maps as easy as possible. + +Instead of manually editing game files, the editor should handle the file formats and let the user work directly with the rendered map. + +More parts of the game will be added as they are figured out. + +--- + +## Game + +This tool is made for: + +**Pokémon Ranger: Shadows of Almia** + +Nintendo DS + +--- + +## Disclaimer + +This is a fan-made project. + +This project is not made by, connected to, or supported by Nintendo, The Pokémon Company, Creatures Inc., or HAL Laboratory. + +Pokémon and Pokémon Ranger are trademarks of their respective owners. + +No Pokémon Ranger ROM or copyrighted game files are included with this project. + +You must provide your own legally obtained copy of the game. + +--- + +## License + +The source code in this repository is released under the license included with the project. + +Game assets, Pokémon graphics, Nintendo DS files, and other copyrighted content extracted from Pokémon Ranger: Shadows of Almia are **not** part of that license. + +--- + +## PRSA Map Editor + +Made to make Pokémon Ranger: Shadows of Almia map editing easier. + +More updates will come as more of the game is figured out.