pumptools/doc/hook/nx2hook.md

nx2hook: NX2

This readme covers any matters that are relevant for this hook, only. Anything that applies to all hooks is covered in a main hook readme file including general data setup and a quick start guide.

Additional notable features

• Removed USB flash drive vendor lock, i.e. use ANY USB flash drive to store game profiles
• Auto generate new profiles if no profile is found on the connected USB flash drive

Versions supported

All known versions supported.

Dependencies

Make sure to read the different methods of dependency resolution available in the main hook readme file, first.

Note: Game is 32-bit, so you need to install the 32-bit versions of the dependencies!

The following direct dependencies (cmd: readelf -d piu) are required:

• libfreetype.so.6
• librt.so.1
• libGL.so.1
• libGLU.so.1
• libusb-0.1.so.4
• libpthread.so.0
• libXxf86vm.so.1
• libpng12.so.0
• libasound.so.2
• libmad.so.0
• libgcc_s.so.1
• libc.so.6
• libm.so.6
• libX11.so.6
• libstdc++.so.6
• libz.so.1

As for method 1, when using Ubuntu, the dependencies can be found in the following packages:

• libc-bin (or gcc-multilib on a 64-bit platform)
• libx11-6
• zlib1g
• libusb-0.1-4
• libasound2

Additionally, nx2hook needs the following direct dependencies for pumpnet:

• libcurl-gnutls.so.4

Ubuntu packages for nx2hook dependencies for pumpnet:

• libcurl4-gnutls

Further indirect dependencies are needed but should be taken care of automatically when using a package manager to install the direct dependencies.

Data setup

In additional to the general information applying to all hooks, this game requires all files and folders from the original game folder to be in UPPERCASE on a case-sensitive file system with the exception of *.txt and *.ttf files in the root of game. Further game asset files and folders from cramfs need to be copied to the game directory. nx.ttf, nxcn.ttf, nxpt.ttf, nxtw.ttf and mission.txt must be lowercase but SCRIPT and its contents must be UPPERCASE.

Pumpnet setup

Instead of using plain usb profiles like on the vanilla version without pumptools (which is still possible with pumptools), pumptools provides a patch module to upload/download usb profiles to/from a remote server over TCP IP networks.

This feature can be enabled by setting the following configuration properties in the hook.conf file:

patch.net_profile.server=<put the server address of the pumpnet server here>
patch.net_profile.machine_id=<put your machine id that's registered with the server here>

If the network offers or even requires secure communication using https, you should have received a package with a client certificate, a client key and a certificate authority bundle. Place the files named ca-bundle-crt.pem, client-crt.pem and client-key.pem in a folder, e.g. cert next to the piu executable and configure the hook to use these for the encrypted communication by setting the property key patch.net_profile.cert_dir_path accordingly, e.g. patch.net_profile.cert_dir_path=./cert. Note: The server URL that you set for the properties key patch.net_profile.server has to be a https based URL in order to work correctly, e.g. https://localhost. Your network provided of your choice should provide you the URL you have to use.

When everything's configured correctly, the log tells you so:

Initialized pumpnet for game 20, serveraddr localhost:8080, main endpoint version /usbprofile/v1
Initialized: game 20, server XXXXXXX, machine id XXXXXXX

How you acquire an address to a remote server and a machine ID is out of this document's scope.

Once these parameters are present, pumptools is looking for a file called pumpnet.bin on connected usb sticks. As long as this file is in the root directory of your usb drive, the game will ignore the the regular nx2save.bin and nx2rank.bin files and always try to connect to the remote server. When you remove pumpnet.bin, it will pick up the local profiles and not connect to the server, even if enabled.

pumpnet.bin contains an identifier for the player to login. This file needs to be provided by the network service somehow. The how is out of the scope of this document.

Ensure you have mapped the usb ports in the game correctly. Go to the operator menu and the "usb drive" item. Plug exactly one usb thumb drive into the usb port you want to assign as P1 and hit the test button. The menu item should change from --- to a numerical value, e.g. 03:00 which describes the bus and port the drive got detected on. Repeat this for P2.

When you start the game, have your usb stick plugged in and it is recognized correctly by the game, the log output tells you if it found the pumpnet.bin file and connected to the server correctly for downloading your profile data:

Found pumpnet profile file /mnt/0/pumpnet.bin
Profile file player 0, file_type 0, refId XXXXXXXXXXXXXX downloading from server...
Downloading file player 0, file_type 0, refId XXXXXXXXXXXXXX successful

If it cannot connect to the server, the log tells you that as well and retries to connect to it a few times before giving up:

Performing curl request failed: Couldn't connect to server
Failed, http code 0, retrying (0)...
...

Troubleshooting and FAQ

Make sure to also check the troubleshooting and FAQ section of the main hook readme. This covers various things that apply to all hooks. The following sub-sections apply mainly to this hook.

How do I unlock 'Tell Me' on the non korean version?

Put an empty file called KEY.LUA into the game/SCRIPT folder and change the language to korean in the operator menu. This loads the korean version of the game (yes, that's how it actually worked originally) and 'Tell Me' will be available.

Note: You can't switch back to English unless you delete the file game/SCRIPT/KEY.LUA.

When using pumpnet, the game does not detect any usb sticks

Make sure that you have configured the usb ports in the game's operator menu USB DRIVE menu item. For instructions, refer to the above section.

When using pumpnet, the game tells me to register my usb drive on login

If you see the message "Please REGISTER your USB drive at www.piugame.com prior to using the product." when logging in with pumpnet enable, your login got rejected for one of the following reasons:

• Your machine ID is invalid or not whitelisted on the server
• Your player ID is invalid or no such player exists on the server
• No NX2 profile was created for the player ID on the server

On any of the above cases, verify that you ensured you have configured everything correctly on the user web interface of pumpnet. Otherwise, contact the server administrator.

When using pumpnet, the game apparently gets stuck on the usb drive login screen

This can happen if the game cannot reach the server or on some other errors that might be temporarily. Therefore, the game retries for up to ten times currently to reach the server or complete an outstanding operation. This is also reflected in the logs with warning messages telling you the game is retrying.

When using pumpnet, the game reports "Nonfunctional USB drive"

Check the pumptools.log file for entries about requests to pumpnet, for example:

[I][2021/4/1-16:32:0:325][pumpnet][pumpnet.c:184] [1234567890123456][1234567890123456] Get save
[M][2021/4/1-16:32:0:326][http][http.c:245] [1234567890123456][https://pumpnet/pumpnet/usbprofile/v1/nx2/save] GET 24 30784
[M][2021/4/1-16:32:1:404][http][http.c:258] [1234567890123456][https://pumpnet/pumpnet/usbprofile/v1/nx2/save] GET: 403 (0 32)
[E][2021/4/1-16:32:1:408][http][http.c:310] [1234567890123456][https://pumpnet/pumpnet/usbprofile/v1/nx2/save][0] Invalid recv data size: 0 != 30784
[E][2021/4/1-16:32:1:408][pumpnet][pumpnet.c:99] [1234567890123456][get][https://pumpnet/pumpnet/usbprofile/v1/nx2/save] Failed
[E][2021/4/1-16:32:1:409][patch-net-profile][net-profile.c:456] Downloading file player 0, file_type 0, refId 1234567890123456 failed

Check the response code of the requests, e.g. GET: 403 (0 32) here. 403 means "forbidden" which is translated to the "Nonfunctional USB drive" message in the game. 403s are reported if you are using an invalid or non-registered machine ID. Check if your machine ID is correctly set in the hook.conf file, see the setup section. Otherwise, contact an administrator of pumpnet.

Curl requests fail: Problem with the SSL CA cert

When you get the following error message:

Performing curl request failed: Problem with the SSL CA cert (path? access rights?)

Make sure the path you configured for the property key patch.net_profile.cert_dir_path is pointing to an existing directory containing the files ca-bundle-crt.pem, client-crt.pem and client-key.pem that you received from the the network you are trying to connect to.

Curl requests fail: SSL peer certificate or SSH remote key was not OK

When you get the following error message:

Performing curl request failed: SSL peer certificate or SSH remote key was not OK

Make sure that you have the files ca-bundle-crt.pem, client-crt.pem and client-key.pem that you have received from the network you are trying to connect to placed in a directory. The path to the directory needs to be set in the hook configuration file by setting the key patch.net_profile.cert_dir_path, e.g. patch.net_profile.cert_dir_path=./cert if the files are placed next to the piu exec in the folder cert.

Do USB 3 ports also work?

No guarantee but various tests have shown that they can work. If you are having issues when assigning the ports in the operator menu or detecting your USB thumb drive on the USB profile screen, try mapping different physical ports on your machine and also try USB 2 and 3 ports (the latter if available).