Native code and the interpreter

Two ways to run a game

A PSP game is machine code for the PSP's processor, a MIPS chip called Allegrex. Your PC can't run that code as it is, so PSPC has two ways to run it:

Native code (ahead of time)

Before the game runs, PSPC's recompiler, pspc-recomp, reads each of the game's executable modules, finds their functions and translates every one into C++. A compiler then builds that into a native module for your PC: a DLL on Windows. At run time there is nothing left to translate. This is how PSPC is meant to run games.

The interpreter

Reads and carries out the game's instructions one at a time while it runs. It works with any game straight away, with no build, but it is much slower.

The two aren't alternatives so much as partners. Every instruction's behavior is written once and shared by both, so they give the same results: the pspautotests suite passes the same 539 of 559 tests either way. And in a native run, the interpreter still takes over any code that has no native version, then hands back to native code as soon as it reaches a compiled function. That covers code the recompiler couldn't find in advance, code a game builds or loads while it runs, and code that cheat plugins patch.

Build a game's native code

1. Select the game

   Click it in the library. The panel on the right shows its native code status.

2. Click Build native code

   Or just click Play and answer Yes when it offers to build first; the game then starts by itself when the build is done.

3. Wait for the build window

   A console window reads the disc, decrypts each executable module and compiles it, showing build steps, progress and estimated time remaining. PSPC estimates about a minute per disc; big games on slower PCs take a few minutes. The game's tag reads BUILDING meanwhile.

4. Done

   The panel says Native code built and the tag reads NATIVE. The result stays cached; rebuild only when PSPC changes or a run discovers usable code the build missed.

On Windows, the installer brings everything a build uses: the recompiler, a portable LLVM/MinGW compiler, the matching AOT SDK and a private Python.

If part of a build fails, PSPC says so (the build window shows why) and offers to play anyway: modules without native code run in the interpreter. The panel notes how many modules couldn't be built. Please report it, with the build window's output.

What the tags mean

Each game in the library can carry a tag, and the panel on the right says the same in words:

Two other messages can appear in the panel. Interpreter only means native code is turned off in Settings. Ready to play: runs in PSPC's interpreter means this copy of PSPC has no tools to build native code, which can happen with a source build that lacks them; the Windows installer always has them.

When to rebuild

• After updating PSPC. Native code is stamped with the version of PSPC's instruction semantics it was built against. If that version changes, PSPC won't load the old code; it runs those modules in the interpreter until you rebuild. The launcher tags such games REBUILD.
• After a run found code the build missed. PSPC records addresses that a rebuild can use, usually functions reached through pointers. The launcher shows REBUILD and explains that the last session ran code the build doesn't cover yet. Rebuilding compiles those addresses too; existing builds already cover 99% or more of the code in the retail games tested.

A rebuild only recompiles what needs it: up-to-date modules are skipped. v0.1.2 fixes games asking to rebuild after every session by recording only usable addresses and writing them only when new ones are found. A game already marked REBUILD before the update may need one last rebuild.

Use the interpreter on purpose

Click Interpreter in the panel, or right-click the game and choose Play in the interpreter, to run it with no native code at all. That is useful in two cases:

• To narrow down a problem. If a game works in the interpreter but not natively, the problem is in the recompiler, which is worth reporting. If it fails both ways, the cause is elsewhere, usually in a system library.
• To play before a build exists, or when one has failed.

To turn native code off everywhere, clear Use native code (AOT) when it is built in Settings. Expect the interpreter to be slow in demanding games: Star Wars Battlefront II's battles, for example, run at about 30% of real time interpreted.

Build from the command line

The launcher runs tools\pspc_build.py, and you can too. In an installed copy, open a terminal in PSPC's folder (%LOCALAPPDATA%\Programs\PSPC) and use its private Python:

python\python.exe -I -B -X utf8 tools\pspc_build.py Games\MyGame.iso
pspc.exe Games\MyGame.iso

The first line builds native code for every module on the disc, the second plays the game. Useful options of pspc_build.py:

• --force rebuilds every module, up to date or not.
• --keep-src keeps the generated C++, if you're curious what your game looks like translated.

From a source checkout, see the recompiler's documentation and PSPC on Linux.

Where native code is kept

Built modules go into PSPC's native code cache: cache\aot in PSPC's folder. Each module is named after the SHA-1 of its decrypted code, so a module that several games share is built once, and moving or renaming a game's file doesn't lose its build.

The cache only holds things PSPC can make again. Deleting it frees the space, and the games simply need building again.