PVSneslib Documentation

PVSnesLib is a development kit for coding Nintendo SNES games in C or assembly. It includes a compiler/linker toolchain (816-tcc) and a library for hardware abstraction.

Key capabilities include:

• Backgrounds: Tile and map loading, support for multiple BG modes.
• Sprites: OAM management helpers for animation.
• Input: Reading controller/pad and mouse/superscope input.
• Sound & Music: Integration with the SPC700 audio driver.
• Memory Support: HiROM and FastROM support.
• Flexibility: Write in C, use assembly for performance-critical sections, or use assembly exclusively.

When using snesbrr, follow these best practices to improve audio quality and file size:

• Minimize File Size: Ensure both the loop start point and the loop size are multiples of 16. If they are not, the tool will automatically repeat samples until they reach a multiple of 16, which can increase file size.
• Improve Audio Quality: Use a higher sampling rate than strictly necessary for the source. Gaussian filtering (used during SNES decoding) reduces high-frequency volume. Increasing the sampling rate offsets this effect.
  • Example: A 4000 Hz square wave requires 8000 Hz minimum. At 8000 Hz, the decoded volume is only ~27%. At 16000 Hz, it reaches ~89%. At 32000 Hz, it reaches ~99%.
• Manual Encoding: For simple waves (Square, Triangle, Sawtooth), you can manually provide BRR block data for maximum quality and smallest size.

If frame timing is not a priority, you can update the entire screen to VRAM by setting the mapdirty flag to 1. This is the simplest way to ensure changes made to mapbuffer[] in RAM are reflected on screen, but it updates the entire screen at once.

mapbuffer[123] = 0x0001;
mapdirty = 1;

To get a project compiling quickly, follow these steps:

1. Download the appropriate release for your operating system from the latest release page and unzip the archive.
2. Set the environment variable PVSNESLIB_HOME to point to the directory where you unzipped the library. This is required for the toolchain to function.
3. Write a Hello World program to verify your setup. For a detailed guide on the Hello World example, refer to the Compiling helloworld-example tutorial.

For advanced details regarding Makefile setup, folder layouts, and flashing to real SNES hardware, consult the Project Wiki.

export PVSNESLIB_HOME="/path/to/pvsneslib"

To build this specific demo using Visual Studio Code, ensure you have the editor installed and the project root directory open. You can trigger the build process using the integrated build task shortcut.

# Build shortcut
Ctrl + Shift + B

To initialize the extension, you must first load your map data into WRAM using mapbuffersLoad, and then point the standard map engine to the mapbuffer instead of the original map data using mapLoad.

#include "mapbufferextension.h"

// 1. Load map data into WRAM
mapbuffersLoad((u8 *)&mapmario, (&mapmario_end - &mapmario));

// 2. Point the map engine to the buffer instead of the original map
mapLoad((u8 *)&mapbuffer, (u8 *)&tilesetdef, (u8 *)&tilesetatt);

#include "mapbufferextension.h"
...
//load map into wram 
mapbuffersLoad((u8 *)&mapmario, (&mapmario_end- &mapmario));
//map engine gets the buffer instead
mapLoad((u8 *)&mapbuffer, (u8 *)&tilesetdef, (u8 *)&tilesetatt);

To build the Capcom logo demo, ensure you have Visual Studio Code installed. Open the root directory of the project in VS Code and use the integrated build task to compile the source code.

1. Open the project root directory in Visual Studio Code.
2. Press Ctrl + Shift + B to trigger the build process.
3. Once the build completes, open the resulting logo.sfc file using a Super Nintendo (SNES) emulator to view the demo.

# Build command via VS Code shortcut
Ctrl + Shift + B

The bin2txt utility is a binary file converter designed for Super Nintendo development. It converts binary files into text-based formats (C or Assembly) so they can be easily included in your source code as data arrays.

bin2txt [options] filename

Once configured, you can manage your project using VS Code tasks:

1. Open your project folder in VS Code (File -> Open Folder...).
2. Press Ctrl + Shift + B to trigger the build tasks.
3. Select from the following tasks:
   • PVSneslib - Build: Compiles the project.
   • PVSneslib - Clean: Removes all object files and temporary files.

Alternatively, you can run build commands manually via the integrated terminal after navigating to your project directory.