Usage - Vita3K/Vita3K GitHub Wiki

Usage

Setup

General items (needed for all installations and systems!)

System Firmware can be found at Sony's official website. Please go to https://www.playstation.com/en-us/support/hardware/psvita/system-software/ or search for the appropriate page for your region.

  • This file will be called PSVUPDAT.PUP.

Font Firmware can be fetched directly from Sony's servers by using the following shortened link (https://bit.ly/2P2rb0r) or this direct link.

  • This file will be called PSP2UPDAT.PUP.

Windows

  1. Verify that your device meets our minimum requirements.
  2. Get the latest release named windows-latest.zip from our GitHub Releases page and place it somewhere you'll remember.
  3. Locate your windows-latest.zip, right click, and press Extract all... to extract the zip file. Optionally, you can rename the windows-latest folder to Vita3K or something else.
  4. Open the windows-latest folder, and launch Vita3k.exe
  5. Go through initial setup. When you are asked to install the firmware files, please install BOTH, using either the buttons in the emulator OR the links at the top of this page.
  6. Vita3K is now ready to use!

Linux (Ubuntu, Debian, Fedora, and other non-Arch systems)

  1. Verify that your device meets our minimum requirements.
  2. Get the latest release named ubuntu-latest.zip from our GitHub Releases page and place it somewhere you'll remember. Despite being named ubuntu-latest, this release should work on most, if not all Linux distributions.
  3. Locate your ubuntu-latest.zip and extract it. This can be done through the cli (mkdir ubuntu-latest; unzip ubuntu-latest.zip -d ubuntu-latest; rm ubuntu-latest.zip), though most file managers provide the ability to extract through a right click menu. Optionally, you can rename the ubuntu-latest folder to Vita3K or something else.
  4. Open the ubuntu-latest folder, and launch the Vita3K executable.
    • You may be required to add the executable permission to the executable. This can be done through the cli (chmod +x Vita3K), though most file managers provide the ability to mark a file as executable through Right Click -> Properties -> Permissions.
  5. Go through initial setup. When you are asked to install the firmware files, please install BOTH, using either the buttons in the emulator OR the links at the top of this page.
  6. Vita3K is now ready to use!

Linux (AppImage)

  1. Verify that your device meets our minimum requirements.
  2. Get the latest AppImage release (Vita3K-x86_64.AppImage) from our GitHub Releases page and place it somewhere you'll remember.
  • With the AppImage build, updates will be handled with AppImageUpdate. You can grab their release from their GitHub Releases page.
    • You'll likely want AppImageUpdate-x86_64.AppImage.
  • Using AppImageUpdate is as simple as launching it and selecting your Vita3K AppImage.
    • There may be a warning about signature validation. As of writing, we do not sign the AppImage release.
  1. Launch the AppImage.
    • You may be required to add the executable permission to the executable. This can be done through the cli (chmod +x Vita3K-x86_64.AppImage), though most file managers provide the ability to mark a file as executable through Right Click -> Properties -> Permissions.
  2. Go through initial setup. When you are asked to install the firmware files, please install BOTH, using either the buttons in the emulator OR the links at the top of this page.
  3. Vita3K is now ready to use!

Linux (Arch/AUR)

  1. Verify that your device meets our minimum requirements.
  2. Choose either vita3k-git or vita3k-bin to install from the AUR.
    • If you choose the -git version, Vita3K will be cloned and built on your system, and updates will be available from your AUR helper, which will check the git for updates.
    • If you choose the -bin version, then the binary release will be downloaded and installed to your system, and updates will be available from within the application or via the updater script (/opt/vita3k/update-vita3k.sh)
  3. Install the appropriate version using your AUR helper. This will often be one of the following:
    • yay: yay -S vita3k-git or yay -S vita3k-bin
    • paru: paru -S vita3k-git or paru -S vita3k-bin
  4. Run vita3k in your terminal.
  5. Go through initial setup. When you are asked to install the firmware files, please install BOTH, using either the buttons in the emulator OR the links at the top of this page.
  6. Vita3K is now ready to use!

MacOS

  1. Verify that your device meets our minimum requirements.
  2. TODO: all of this

Android

  1. Verify that your device meets our minimum requirements.
  2. Download the latest Android release from our Android GitHub Releases page.
  3. Locate the appropriate .apk file you have just downloaded, and install it using your file manager of choice.
  4. Launch Vita3K.
  5. Go through initial setup. When you are asked to install the firmware files, please install BOTH, using either the buttons in the emulator OR the links at the top of this page.
  6. Vita3K is now ready to use!

Installing Games

VITAMIN DUMPS ARE COMMERCIAL GAMES IN .VPK FORMAT. THEY ARE NOT, AND WILL NEVER BE SUPPORTED. .VPK SHOULD BE ONLY FOR HOMEBREW.

Q: What can I do about this?

A: Re-dump your game with a different tool. If you did not dump your game (or downloaded them from online), then you are engaging in digital piracy. You will NOT receive help from the Vita3K team for pirated games.

Installation Instructions

Open the emulator and select File, then the appropriate file format that your game is in.

  • NoNpDrm dumps are often in .zip format. These dumps contain the license in their files. By default, the contents are encrypted.
  • Decrypted dumps are often in .zip format. These dumps do not contain a license, and are decrypted already. These dumps often come from FAGDec or psvpfstools decryption.
  • TODO: more info about licenses and encrypting/decrypting?
  • .pkg games are encrypted, and are packages downloaded directly from Sony's servers.
    • .pkg games REQUIRE a license (work.bin/.rif) or zRIF string. You can acquire the license from your physical PS Vita using the NoNpDrm plugin
      • A zRIF string is a base64 representation of the original license file. You can convert between them if you do so desire using this site.
    • If you acquire a license for a game that you do not own, this is Piracy. Do not ask us where to get licenses. You will not receive support from us.
  • IF YOU ACQUIRE A LICENSE FOR A GAME YOU DO NOT OWN, THIS IS PIRACY. DO NOT ASK US WHERE TO GET LICENSES. YOU WILL NOT RECEIVE SUPPORT FROM US.

IF YOU ACQUIRE A LICENSE FOR A GAME YOU DO NOT OWN, THIS IS PIRACY. DO NOT ASK US WHERE TO GET LICENSES. YOU WILL NOT RECEIVE SUPPORT FROM US.

Dumping Instructions

TODO: create dumping guide (Don't use MaiDump or Vitamin!)

Texture Import/Export (PC only for now!)

Texture Import/Export allows textures to be exported and imported on the fly using Vita3K. This allows texture packs to be created for games running under Vita3K.

If you are just interested in using texture import/export and don't care about details, see Using Texture Import or Using Texture Export

If you are interested in using HD texture packs, see Using HD Texture Packs

General Information

Under Vita3K, each processed texture is issued a unique hash. This hash is based on the the exact content of the first mip of the first face of the texture. Some information is also added (texture format, swizzle, dimensions and if it is gamma corrected) in order to calculate this hash. This hash is a 64-bit hash. When a texture is exported, the resulting filename is the hexadecimal representation of the hash for the texture as calculated by Vita3K.

For texture importing, when Vita3K attempts to load a texture, it first calculates the hash of the texture, and then proceeds to check if a texture with a filename matching the original hash exists within the import folder. If a file is found with a name matching the original hash, then Vita3K will instead load that texture.

Texture Import/Export is renderer-agnostic, meaning you can use it in both OpenGL and Vulkan.

TL;DR: Textures exported from texture import under the GPU tab do NOT have their original filename. Thus, when replacing textures, filenames matching Vita3K's unique hashing system must be used.

Texture locations

Inside Vita3K, click File in the top left and then Open Textures Path. If for some reason this doesn't work or takes you to the incorrect place, default locations are listed below.

Windows: Locate the folder with Vita3K.exe. There will be a folder titled textures.

MacOS: TODO

Linux: $HOME/.local/share/Vita3K/textures/ by default if your distro supports XDG_DATA_DIRS. Else, it will be placed next to the Vita3K executable as a folder titled textures.

For all systems, exported textures will be in textures/export/TITLEID/ where TITLEID is the appropriate Title ID for your game.

For all systems, imported textures will be in textures/import/TITLEID/ where TITLEID is the appropriate Title ID for your game.

  • This is where you would place texture packs.

Using Texture Export

Texture Import/Export is disabled by default. To ENABLE texture import or export, open Vita3K and go to Configuration -> Settings -> GPU and scroll down. You can then tick the box to enable either import or export. If export is enabled, Vita3K will dump the textures as they are loaded/requested by the game. Thus, to dump a texture, you must see it in-game.

Here, you can also choose the format for your textures.

  • PNG will dump the rendered textures in .png format. This format is supported by most image viewers and devices, and is easily editable. However, it has a few drawbacks. .png may lose texture quality because of compression and conversion to 8-bit per component format. This format also does not support mipmaps and cubemaps.
  • DDS (DirectDraw Surface) contains the raw texture in .dds format. This kind of texture will NOT have compression applied. Additionally, DDS supports mipmaps and cubemaps. The main drawback of .dds is that it is not widely supported, but some image editors like GIMP are able to view and edit it.
    • It is worth noting that if the raw .dds texture was compressed, it will still be compressed in the dump.

For all systems, exported/dumped textures will be in textures/export/TITLEID/ where TITLEID is the appropriate Title ID for your game.

TL;DR: to export, tick the "Export Textures" box in Configuration -> Settings -> GPU. Exported textures will appear in the location referred to here, inside a folder corresponding to the Title ID of your game. The names of the textures are not the names inside the game files, but a custom name that Vita3K uses for textures internally.

Using Texture Import

Texture Import/Export is disabled by default. To ENABLE texture import or export, open Vita3K and go to Configuration -> Settings -> GPU and scroll down. You can then tick the box to enable either import or export. Vita3K will load textures in the import folder as they are loaded/requested by the game.

  • To import textures, first locate the appropriate textures folder for your platform.
    • Inside the textures folder, if an import folder does not exist, create it.
    • Inside the import folder, if a folder corresponding to your game's Title ID does not exist, create it.
  • Add appropriately named textures to the corresponding Title ID folder.
    • The names of the textures should match up with Vita3K's internal names for them, and not the names provided by the game files. As of writing, the only way to get these names is to export textures first and find what textures correspond to what filename.

Using HD Texture Packs

This tutorial assumes you have already installed your game.

  1. Locate the appropriate textures folder for your platform.
    • Inside the textures folder, if an import folder does not exist, create it.
  2. Extract your HD Texture pack.
    • More often than not, texture packs will end up in a folder with the Title ID for the game it is meant for. If this is not the case, create a folder with the appropriate Title ID inside the import folder.
  3. Move the folder with the Title ID to the import folder. Your files should look like this.
  4. Open Vita3K, go to Configuration -> Settings -> GPU and scroll down to tick the "Import Textures" box.
  5. Launch your game. The HD Textures should now be applied!

To disable HD Textures, untick the "Import Textures" box.