123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# SplashEdit
|
||
|
||
SplashEdit is a Unity Package that converts your Unity scenes into authentic PSX worlds by exporting binary data loadable in a PlayStation 1 game. It streamlines the export process for your scenes and offers additional tools for VRAM management and texture quantization.
|
||
|
||
## Features
|
||
|
||
- **Automatic Scene Exporting:**
|
||
Export your scene with a single click using the PSX Scene Exporter component. This process automatically packs textures into the PSX's 2D VRAM.
|
||
- **Texture Packing & Quantization:**
|
||
Convert and preview your textures in a PSX-compatible format with built-in quantization tools.
|
||
|
||
## Installation
|
||
|
||
Install SplashEdit directly from the Git repository using Unity's Package Manager:
|
||
|
||
1. **Open Unity's Package Manager:**
|
||
Go to `Window` → `Package Manager`.
|
||
|
||
2. **Add Package from Git URL:**
|
||
Click the **+** button in the upper left corner and select **"Add package from git URL..."**.
|
||
Enter the Git URL for SplashEdit: `https://github.com/psxsplash/splashedit.git`
|
||
Click **Add** and wait for the package to install.
|
||
|
||
## Usage
|
||
|
||
### General Scene Exporting
|
||
|
||
If you only need to export the scene, follow these steps:
|
||
|
||
1. **PSX Object Exporter:**
|
||
- Attach the **PSX Object Exporter** component to every GameObject you wish to export.
|
||
- Set the desired bit depth for each object's texture in the component settings.
|
||
|
||
2. **PSX Scene Exporter:**
|
||
- Add the **PSX Scene Exporter** component to a GameObject in your scene (using an empty GameObject is recommended for organization).
|
||
- Click the export button in the PSX Scene Exporter. You will be prompted to choose an output file location.
|
||
- The exporter will automatically handle texture packing into the PSX's 2D VRAM.
|
||
|
||
### Additional Features
|
||
|
||
SplashEdit also includes extra tools to enhance your workflow:
|
||
|
||
1. **VRAM Editor:**
|
||
- Access the VRAM Editor via Unity's **Window** context menu.
|
||
- Set framebuffer locations and preview texture packing.
|
||
- **Important:** Click on **Save Settings** in the VRAM Editor to inform the PSX Scene Exporter where to pack textures.
|
||
- When you click **Pack Textures** in the VRAM Editor, a file selection dialog will appear.
|
||
- Selecting a file will save only the VRAM data.
|
||
- If you do not wish to save VRAM, simply close the dialog.
|
||
**Note:** This action only exports the VRAM. For a complete scene export (including VRAM), use the PSX Scene Exporter component.
|
||
|
||
2. **Quantized Texture Preview:**
|
||
- Preview how your textures will look after quantization before exporting.
|
||
|
||
## Texture Requirements
|
||
|
||
- **Power of Two:**
|
||
All textures must have dimensions that are a power of two (e.g., 64x64, 128x128, 256x256) with a maximum size of **256x256**.
|
||
- **No Automatic Downscaling:**
|
||
SplashEdit does not automatically downscale textures that exceed these limits.
|
||
- **READ/WRITE Enabled:**
|
||
Ensure all textures have **READ/WRITE enabled** in Unity.
|
||
|
||
## Output Format
|
||
|
||
The binary file output by SplashEdit is structured as follows, allowing a programmer to write a parser in C based solely on this specification.
|
||
|
||
1. **VRAM Data (1 MB):**
|
||
- The file begins with a 1 MB block of VRAM data.
|
||
- This data is generated by iterating through a 2D array (`vramPixels`) in row-major order.
|
||
- Each pixel is written using its `.Pack()` method (resulting in one byte per pixel).
|
||
|
||
2. **Object Count:**
|
||
- Immediately following the VRAM data, a 2-byte unsigned short is written indicating the number of exported objects (PSXObjectExporters).
|
||
|
||
3. **Per-Object Data:**
|
||
For each exported object, the following data is written sequentially:
|
||
|
||
- **Triangle Count (2 bytes):**
|
||
An unsigned short representing the number of triangles in the object's mesh.
|
||
|
||
- **Texture Information:**
|
||
- **Bit Depth (1 byte):**
|
||
The bit depth of the object's texture.
|
||
- **Texpage Coordinates (2 bytes total):**
|
||
Two 1-byte values for `TexpageX` and `TexpageY`.
|
||
- **CLUT Packing (4 bytes total):**
|
||
Two unsigned shorts (2 bytes each) for `ClutPackingX` and `ClutPackingY`.
|
||
|
||
- **Packing Byte (1 byte):**
|
||
|
||
|
||
- **Triangles Data:**
|
||
For each triangle in the object's mesh, data for its three vertices is written in sequence. Each vertex consists of:
|
||
|
||
- **Position (6 bytes):**
|
||
Three signed shorts (2 bytes each) representing `vx`, `vy`, and `vz`.
|
||
- **Normal (6 bytes):**
|
||
Three signed shorts representing `nx`, `ny`, and `nz`.
|
||
- **Texture Coordinates (2 bytes):**
|
||
- **U coordinate (1 byte):**
|
||
The U coordinate relative to texpage start
|
||
- **V coordinate (1 byte):**
|
||
The V coordinate relative to texpage start
|
||
- **Color (3 bytes):**
|
||
Three bytes representing the RGB values.
|
||
- **Padding (7 bytes):**
|
||
Seven bytes of zero padding.
|
||
|
||
Each vertex is 24 bytes in total, making each triangle 72 bytes (3 vertices × 24 bytes).
|
||
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome! To contribute:
|
||
|
||
1. Fork the repository.
|
||
3. Submit a pull request with your changes.
|
||
|
||
For major changes, please open an issue first to discuss your ideas.
|
||
|
||
|