secretsplash/README.md

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.

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 in row-major order.

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.
2. Submit a pull request with your changes.

For major changes, please open an issue first to discuss your ideas.