Initialize README for PRSA Map Editor

Add README.md for PRSA Map Editor with features and usage instructions.
2026-09-06 19:28:00 -05:00 · 2026-08-17 20:10:26 -04:00
parent 9e7e554468
commit a98bb66acc
1 changed files with 469 additions and 0 deletions
--- a/README.md
+++ 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.