perfect_dark/README.md

Perfect Dark port (port-net)

Experimental netplay branch

This branch of the port contains an extremely early and experimental implementation of network play.
DISCLAIMER: This is NOT READY for prime time. Use at your own risk if you are not a developer.
Do not create issues about problems in this branch until this disclaimer is gone.

See this file for more information on how this works.

Original description

This repository contains a work-in-progress port of the Perfect Dark decompilation to modern platforms.

To run the port, you must already have a Perfect Dark ROM, specifically one of the following:

• ntsc-final/US V1.1/US Rev 1 (md5 e03b088b6ac9e0080440efed07c1e40f).
  This is the recommended version to use.
  Called NTSC version 8.7 final on the boot screen.
• ntsc-1.0/US V1.0 (md5 7f4171b0c8d17815be37913f535e4e93).
  Technically supported, but not recommended.
  Called NTSC version 8.7 final on the boot screen as well.
• jpn-final (md5 538d2b75945eae069b29c46193e74790).
  Technically supported, but requires a separate custom-built executable.
  Called JPN version 8.9 final on the boot screen.
• pal-final (md5 d9b5cd305d228424891ce38e71bc9213).
  Technically supported, but requires a separate custom-built executable.
  Called PAL 8.7 final on the boot screen.

Status

The game is in a mostly functional state, with both singleplayer and split-screen multiplayer modes fully working.
There are minor graphics- and gameplay-related issues, and possibly occasional crashes.

The following extra features are implemented:

• mouselook;
• dual analog controller support;
• widescreen resolution support;
• configurable field of view;
• 60 FPS support, including fixes for some framerate-related issues;
• fixes for a couple original bugs and crashes;
• basic mod support, currently enough to load a few custom levels;
• on Android: an on-screen controller, mod installation and netplay (see the Android sections below);
• slightly expanded memory heap size;
• experimental high framerate support (up to 240 FPS):
  • enable Uncap Tickrate in Extended Video Options to activate;
  • in practice the game will have issues running faster than ~165 FPS, so use VSync or Video.FramerateLimit to cap it.
• emulate the Transfer Pak functionality the game has on the Nintendo 64 to unlock some cheats automatically.

The following platforms are officially supported and tested:

• Windows 7+: i686, x86_64
• Linux: i686, x86_64
• MacOS: x86_64 (OS 10.9+), arm64 (OS 11.0+)
• Nintendo Switch: arm64
• Android 5.0+ (API 21): arm64-v8a, armeabi-v7a, x86_64, x86

Download

Latest automatic builds of the netplay branch for supported platforms:

• x86_64-windows (port-net)
• i686-windows (port-net)
• x86_64-linux (port-net)
• i686-linux (port-net)

If you are looking for regular builds (the port branch), see this link.

Running

You must already have a Perfect Dark ROM to run the game, as specified above.

This assumes that you're using an x86_64 build. If you aren't, replace x86_64 below with your arch (e.g. i686).

1. Create a directory named data next to pd.x86_64 if it's not there.
2. Put your Perfect Dark NTSC ROM named pd.ntsc-final.z64 into it.
3. Run the pd.x86_64 executable.

If you want to use a PAL or JPN ROM instead, put them into the data directory and run the appropriate executable:

• PAL: ROM name pd.pal-final.z64, executable name pd.pal.x86_64.
• JPN: ROM name pd.jpn-final.z64, executable name pd.jpn.x86_64.

Optionally, you can also put your Perfect Dark for GameBoy Color ROM named pd.gbc in the data directory if you want to emulate having the Nintendo 64's Transfer Pak and unlock some cheats automatically.

Optionally, you can move the data folder to ~/.local/share/perfectdark on Linux or ~/Library/Application Support/perfectdark on MacOS.

Note that users with different ROMs can't play netgames with each other.

Additional information can be found in the wiki.

A GPU supporting OpenGL 3.0/ES3.0 or above is required to run the port.

Android

1. Install the APK and launch it.
2. Press Select ROM and pick your Perfect Dark NTSC .z64. It is copied into the app's own storage at Android/data/com.perfectdark.port/files/data/pd.ntsc-final.z64, so no storage permissions are needed.
3. Press Play.

On-screen controls. They appear automatically and are hidden while a physical controller is connected. In game:

• tap the ◎ button in the top left to hide or show the overlay;
• hold ◎ to rearrange it -- drag a control to move it, pinch it to resize it, press Back when you are done. The layout is remembered per device;
• opacity and look sensitivity are on the launcher screen, along with Reset control layout.

The default layout mirrors the N64 pad: a single analog stick bottom left driving all movement, and the C buttons in their diamond bottom right. How the stick splits between walking and turning is the game's own Control Style setting, exactly as on hardware, and the C buttons look up and down and sidestep. FIRE and AIM sit along the top edge for the index fingers. Every button is labelled with what it does and, underneath, the N64 button it maps to: FIRE/Z, AIM/R, USE/A, BACK/B, plus CROUCH, START and ~ for the console. Weapons cycle by holding USE and tapping FIRE or AIM, as on the N64.

The port's extra buttons -- alt-fire toggle, the reload hack, weapon next/prev and the radial menu -- are gated to CONTROLMODE_PC in bondmove.c, so they do nothing in the N64 control style and are deliberately absent from the overlay rather than sitting there dead. Crouch is the exception: it rides on synthetic pad bits (CONT_8000 and friends) that no real N64 controller has, so it cannot collide with anything and now runs in every control style.

There is deliberately no second stick, and Android defaults Game.PlayerN.ExtendedControls to 0 to match. With extended ("PC") controls on, the game runs control style CONTROLMODE_PC, where walking and strafing come from the second stick and the C buttons step forward and back -- so a single-stick touch layout ends up driving aim while the C buttons do the walking. Turning it off selects control style 1.1, the N64 default: the stick walks and turns, and the C buttons look and sidestep.

Set ExtendedControls=1 in pd.ini if you would rather have the PC scheme with a gamepad. Note that pd.ini wins over the default, so an install that already has the file keeps whatever is in it; either edit that line or pick a control style from the in-game options.

Controls are positioned in dp from the nearest screen corner rather than as a fraction of the viewport, so they stay the same physical size and keep their grouping from 16:9 all the way out to 21:9 -- a fraction-based layout flings the buttons apart and shrinks them on the wide, short screens that landscape phones actually have.

Mods. Put a mod in a .zip and press Import .zip on the launcher screen. It is unpacked to Android/data/com.perfectdark.port/files/mods/<name>/ and the selected mod is passed to the game as --moddir, which overlays it on top of the ROM's files. Select None to play unmodified. Mods can also be copied into that folder by hand.

Netplay. Choose Network Game from the main menu; see the netplay section at the top of this file for how hosting and joining work. Everyone must be on the same ROM and the same mod. Hosting requires the server port (27100 by default) to be reachable, which usually rules out mobile data, so host over Wi-Fi or let someone else host. Tap ~ to open the console for chat -- the on-screen keyboard comes up on its own when the game asks for text.

Installing the Nintendo Switch version

The Nintendo Switch build ZIP comes with all 3 regions in different folders: perfectdark, perfectdark_pal and perfectdark_jpn.

Take the folder for the region you want and put it into the /switch folder on your SD card, then put your ROM into the data folder inside of the folder you extracted as described above.

port-net currently does not work on the Switch.

Controls

1964GEPD-style and Xbox-style bindings are implemented.

N64 pad buttons X and Y (or X_BUTTON, Y_BUTTON in the code) refer to the reserved buttons 0x40 and 0x80, which are also leveraged by 1964GEPD.

Support for one controller, two-stick configurations are enabled for 1.2.

Note that the mouse only controls player 1.

Controls can be rebound in pd.ini. Default control scheme is as follows:

Action	Keyboard and mouse	Xbox pad	N64 pad
Fire / Accept	LMB/Space	RT	Z Trigger
Aim mode	RMB/Z	LT	R Trigger
Use / Cancel	E	N/A	B
Use / Accept	N/A	A	A
Crouch cycle	N/A	L3	0x80000000 (Extra)
Half-Crouch	Shift	N/A	0x40000000 (Extra)
Full-Crouch	Control	N/A	0x20000000 (Extra)
Reload	R	X	X (0x40)
Previous weapon	Mousewheel forward	B	D-Left
Next weapon	Mousewheel back	Y	Y (0x80)
Radial menu	Q	LB	D-Down
Alt fire mode	F	RB	L Trigger
Alt-fire oneshot	F + LMB or E + LMB	A + RT or RB + RT	A + Z or L + Z
Quick-detonate	E + Q or E + R	A + B or A + X	A + D-Leftor A + X

Building

Windows

1. Install MSYS2.
2. Open the MINGW64 prompt if building for x86_64, or the MINGW32 prompt if building for i686. (NOTE: do not use the MSYS prompt)
3. Install dependencies:
   pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-SDL2 mingw-w64-x86_64-zlib mingw-w64-x86_64-cmake mingw-w64-x86_64-python3 mingw-w64-i686-toolchain mingw-w64-i686-SDL2 mingw-w64-i686-zlib mingw-w64-i686-cmake mingw-w64-i686-python3 make git
4. Get the source code:
   git clone -b port-net --recursive https://github.com/fgsfdsfgs/perfect_dark.git && cd perfect_dark
5. Run cmake -G"Unix Makefiles" -Bbuild ..
   • Add -DROMID=pal-final or -DROMID=jpn-final at the end of the command if you want to build a PAL or JPN executable respectively.\
6. Run cmake --build build -j4 -- -O.
7. The resulting executable will be at build/pd.x86_64.exe (or at build/pd.i686.exe if building for i686).
8. If you don't know where you downloaded the source to, you can run explorer . to open the current directory.

Linux

1. Ensure you have gcc, g++ (version 10.0+), make, cmake, git, python3 and SDL2 (version 2.0.12+), libGL and ZLib installed on your system.
   • If you wish to crosscompile, you will also need to have libraries and compilers for the target platform installed, e.g. gcc-multilib and g++-multilib for x86_64 -> i686 crosscompilation.
2. Get the source code:
   git clone -b port-net --recursive https://github.com/fgsfdsfgs/perfect_dark.git && cd perfect_dark
3. Run the following command:
   • cmake -G"Unix Makefiles" -Bbuild .
   • Add -DROMID=pal-final or -DROMID=jpn-final at the end of the command if you want to build a PAL or JPN executable respectively.
   • Add -DCMAKE_C_FLAGS=-m32 -DCMAKE_CXX_FLAGS=-m32 at the end of the command if you want to crosscompile from x86_64 to x86.
4. Run cmake --build build -j4.
5. The resulting executable will be at build/pd.<arch> (for example build/pd.x86_64).

MacOS

1. Set up Homebrew.
2. Install dependencies:
   • Execute command: brew install cmake gcc python3 zlib git
3. Install SDL2:
   • Execute commands:

     wget http://libsdl.org/release/SDL2-2.30.9.dmg -O SDL2.dmg
     hdiutil mount SDL2.dmg
     sudo cp -vr /Volumes/SDL2/SDL2.framework /Library/Frameworks
     hdiutil detach /Volumes/SDL2
     

   • This installs SDL2 system-wide and this is how the automatic builds are done. The game will also look for it in the executable path, so you could download it locally instead.
4. Get the source code:
   git clone --recursive https://github.com/fgsfdsfgs/perfect_dark.git && cd perfect_dark
5. Configure:
   • Execute command: cmake -G"Unix Makefiles" -Bbuild -DCMAKE_OSX_ARCHITECTURES=x86_64 .
   • Replace x86_64 with arm64 if building for an ARM64 Mac.
   • Add -DROMID=pal-final or -DROMID=jpn-final at the end of the command if you want to build a PAL or JPN executable respectively.
6. Build:
   • Execute command: cmake --build build --target pd -j4 --clean-first
7. The resulting executable will be at build/pd.<arch> (for example build/pd.x86_64).
   • You might need to execute chmod +x build/pd.x86-64 before you can run it.

Nintendo Switch

1. Set up the devkitA64 environment.
   • On Windows you can do it under MSYS2 or WSL, usually MSYS2 is recommended.
   • If using MSYS2, make sure to use the MSYS2 shell, not MINGW32 or MINGW64.
2. Install host dependencies:
   • On MSYS2: execute command pacman -Syuu && pacman -S git make cmake python3
   • On Linux: use your package manager as normal to install the above dependencies.
3. Install Switch toolchain and dependencies:
   • Execute commands:

     dkp-pacman -Syuu
     dkp-pacman -S devkitA64 libnx switch-zlib switch-sdl2 switch-cmake dkp-toolchain-vars
     

   • If in MSYS2 or dkp-pacman doesn't work, replace it with just pacman.
4. Get the source code:
   git clone --recursive https://github.com/fgsfdsfgs/perfect_dark.git && cd perfect_dark
5. Ensure devkitA64 environment variables are set:
   • Execute command: source /opt/devkitpro/switchvars.sh
   • If your $DEVKITPRO path is different, substitute that instead or set the variables manually.
6. Configure:
   • Execute command: aarch64-none-elf-cmake -G"Unix Makefiles" -Bbuild .
   • Add -DROMID=pal-final or -DROMID=jpn-final at the end of the command if you want to build a PAL or JPN executable respectively.
7. Build:
   • Execute command: make -C build -j4
8. The resulting executable will be at build/pd.arm64.nro.

Android

1. Install Android Studio, or just the Android SDK command line tools.
2. Using the SDK manager, install: SDK Platform 36, Build Tools 36.x, NDK 30.0.15729638 and CMake 3.22.1.
3. Get the source code: git clone --recursive https://github.com/fgsfdsfgs/perfect_dark.git && cd perfect_dark
4. Point the build at your SDK, either by exporting ANDROID_HOME or by writing sdk.dir=/path/to/Android/Sdk into android/local.properties.
5. Build:
   • Execute command: cd android && ./gradlew assembleDebug
   • The APK will be at android/app/build/outputs/apk/debug/app-debug.apk.
   • For a signed release build, put a keystore.properties next to android/build.gradle with storeFile, storePassword, keyAlias and keyPassword, then run ./gradlew assembleRelease.

The Gradle build drives the same root CMakeLists.txt as every other platform, so the native code is shared; only android/ and the ANDROID blocks in port/ are Android specific.

Notes

Alternate compilers or toolchains can be specified by passing -DCMAKE_TOOLCHAIN_FILE=whatever as normal. The port does not build with Visual Studio.

You will need to provide a jpn-final or pal-final ROM to run executables built for those regions, named pd.jpn-final.z64 or pd.pal-final.z64.

It might be possible to build and run the game on platforms that are not specified in the supported platforms list (e.g. Linux on armv7), but this has not been tested.

Credits

• the original decompilation project authors;
• Ryan Dwyer for the above, additional help, and pd-extract;
• doomhack for the only other publicly available PD porting effort I could find;
• sm64-port authors for the audio mixer and some other changes;
• Ship of Harkinian team, Emill and MaikelChan for the libultraship version of fast3d that this port uses;
• lieff for minimp3;
• Mouse Injector and 1964GEPD authors for some of the 60FPS- and mouselook-related fixes;
• Raf for the 64-bit port;
• NicNamSam for the icon;
• everyone who has submitted pull requests and issues to this repository and tested the port;
• probably more I'm forgetting.