Usage Guide Physical Device

Using NKAS - Android Physical Device

⚠️ Risk notice (read first)

• Without virtual display mode, the device system resolution is changed, which may cause various issues

This guide applies to non-rooted Android phones. There are two setups:

• NKAS on PC + game on Android phone (recommended)
• NKAS on Android phone + game on Android phone (in testing)

---

NKAS on PC + game on Android phone

How it works: NKAS runs on the PC and connects to the phone over adb (USB or wireless debugging); all screenshots and control go through the adb channel.

1. Enable Developer Options

1. Go to Settings → About phone.
2. Tap Build number about 7 times until you see "You are now a developer".

2. Enable USB Debugging / Wireless Debugging

Open Developer options and turn on debugging. There are three ways to connect; pick one:

💡 Run all adb commands below in the NKAS Console: sidebar System → Console. The console is off by default; enable it first on the Deploy page via the "Enable Web Console" switch.

Option 1: Wireless debugging (Android 11+, recommended)

1. Turn on Wireless debugging.
2. Open the wireless debugging details page and note the IP address and port (e.g. 192.168.1.65:39165).
3. Enter that IP:port as the Serial in NKAS; NKAS will run adb connect automatically.

⚠️ The wireless debugging port is random: it changes every time you toggle wireless debugging off and on. If the connection fails, check the current port on the phone first.

Option 2: USB debugging (wired)

1. Connect the phone to the PC with a USB cable.
2. Turn on USB debugging.
3. When the phone asks "Allow USB debugging?", check Always allow and confirm.
4. Verify the connection in the NKAS Console:

   adb devices
   

   It works if the device appears with status device, for example:

   List of devices attached
   0123456789ABCDEF   device
   

   If the status is unauthorized, the authorization prompt on the phone has not been confirmed yet; if it is offline, replug the cable or try another one.
5. Enter the serial shown by adb devices (0123456789ABCDEF in the example) as the Serial in NKAS.

Option 3: USB debugging, wireless via adb tcpip

Older phones (Android 10 and below) have no Wireless debugging toggle. You can switch adbd to TCP mode with adb tcpip instead; the port is fixed at 5555 and does not change:

1. Connect the phone over USB as in Option 2 and confirm it shows up in adb devices.
2. Switch adbd to TCP mode in the console:

   adb tcpip 5555
   

   restarting in TCP mode port: 5555 means success.
3. Unplug the USB cable. The phone and the PC must be on the same LAN (same WiFi).
4. Find the phone's LAN IP: Settings → WLAN → tap the connected WiFi (e.g. 192.168.1.65).
5. Connect in the console:

   adb connect 192.168.1.65:5555
   

   connected to 192.168.1.65:5555 means success.
6. Run adb devices again to confirm; the list should show 192.168.1.65:5555 device.
7. Enter 192.168.1.65:5555 as the Serial in NKAS (use your phone's actual IP).

⚠️ TCP mode does not survive a phone reboot: after rebooting, reconnect over USB and run adb tcpip 5555 again.

⚠️ Wireless connections require the phone and PC on the same LAN; if it fails, check whether the phone IP changed and whether both are on the same network.

3. Configure NKAS / the game

Go to Instance → NKAS (⚙️) → NKAS Settings in the sidebar, Client Settings group:

Setting	What to enter on a physical device
Client Platform	ADB (Emulator/Device)

Go to Instance → NKAS (⚙️) → Emulator in the sidebar, ADB Settings group:

Setting	What to enter on a physical device
Serial	Option 1: IP:port from the wireless debugging page; Option 2: the USB serial; Option 3: the IP:5555 used with adb connect
Screenshot Method	ADB
Control Method	MaaTouch (recommended) / uiautomator2 (requires installing uiautomator2)

Physical Device group:

• Enable physical device mode: turn on.
• Run game on a virtual display: recommended; see "4. Virtual display mode".
• Auto restore resolution on stop: resolution mode only; recommended to keep on — see "5. Resolution mode".
• Resolution control: resolution mode only; the "Set resolution" / "Restore resolution" buttons switch manually.

In-game settings:

Same as the emulator version — set the language to Simplified Chinese and enable Bloom and Color Grading (see the game settings section of the Emulator Guide).

4. Virtual display mode (recommended)

Enable Run game on a virtual display in the Physical Device group:

• When the instance starts, a 720x1280 @ 240dpi virtual display is created inside Android. The game runs in it; NKAS captures frames and sends input directly to it. The physical screen resolution stays untouched and the phone remains usable.
• The game is restarted into the virtual display on start; the virtual display is released on stop, and force-stops are cleaned up by the WebUI process.

5. Resolution mode (alternative)

NKAS templates and coordinates are based on 720x1280 @ 240dpi. In resolution mode the workflow on a physical device is:

1. When the instance starts: the phone resolution is automatically set to 720x1280, DPI 240.
2. When the instance stops: wm size reset + wm density reset restore the native resolution automatically.

⚠️ Changing the resolution kills foreground apps. If the game is already in the foreground, starting the script will cold-start it — the correct order is to start NKAS first and let the script launch the game itself. Stopping the script also reloads a running game when the resolution is restored.

6. Miscellaneous

• Auto-unlock: not supported yet.
• Some notch/punch-hole displays may not be supported: the top of the game screen is occupied, and while some systems let you adjust the related settings, others do not.

---

NKAS on Android phone + game on Android phone

Option 1: NKAS Mobile APK (recommended)

NKAS Mobile is the official Android app: it downloads and installs Termux, deploys the NKAS environment, connects to the local wireless debugging endpoint, and opens the Web UI on the phone. The APK is currently not published in GitHub Releases; download it from the project QQ group (823265807).

Before you start

1. Android 11 or newer, ARM64 device.
2. A network that can reliably access GitHub (initialization downloads Termux, the NKAS source, and the container).
3. Allow NKAS Mobile and Termux to autostart, launch each other, and run in the background; set their battery policy to Unrestricted where available (the wording differs by vendor).
4. Enable Wireless debugging in Developer options.

Install and initialize

1. Install the APK and complete the Star verification shown on first launch.
2. Open Initialization from the sidebar. The upper Environment preparation section has three requirements:
   • Termux: if it is not installed, tap the bottom button and the app downloads and installs the latest Termux build matching your device architecture; you can also install it yourself from Termux GitHub Releases — do not use the Google Play build.
   • Android external command permission: tap the button to grant it; some systems never show the prompt, so allow "Run commands in Termux environment" manually in the system app permission settings.
   • Termux external-app setting: run the command shown on that step in Termux (use Copy command instead of typing it), fully exit and reopen Termux, then return to NKAS Mobile and check again.
3. Once environment preparation is complete, tap Start installation. The app runs five steps in order — Termux tools, NKAS source, project configuration, container, and container service. Finished steps collapse automatically; tap a step title to expand its logs.
4. Keep NKAS Mobile in the foreground with a stable network, and do not lock the screen or switch away. After a failure, tap Retry installation — the app resumes from the artifacts already present, without clearing data or reinstalling the APK.

Device connection (wireless debugging)

After installation, the Device connection section at the bottom connects the local ADB device:

1. Turn on Wireless debugging (the in-app button jumps straight to the system setting). The app discovers the local port through mDNS and fills it in; if discovery fails, enter the port shown on the wireless debugging page manually in "ADB device connection" — it is saved automatically when the field loses focus.
2. First use requires one pairing: tap Pair, open "Pair device with pairing code" on the wireless debugging page, and enter the pairing code in the notification that appears. After pairing, the app connects automatically and the step shows Connected.
3. Later sessions connect directly as long as wireless debugging is on — no need to pair again. However, the port changes every time wireless debugging is toggled off and on; if the connection fails, reopen Initialization and re-enter the port or check again.

Open the NKAS UI

1. When everything is done, the bottom button becomes Open NKAS UI. Configure instances and start tasks in the Web UI; the APK does not start NIKKE automatically.
2. Before opening, the app checks whether the Serial in config/nkas.json matches the current device and asks before overwriting it.
3. Initialization logs can be viewed on the Logs page in the sidebar.

Common issues

• Stuck on requesting Termux: fully exit and reopen Termux, confirm allow-external-apps=true took effect, and check that NKAS Mobile's external command permission is granted.
• Wireless debugging not detected / connection failed: confirm wireless debugging is on and the device has been paired. Use the port currently shown by Android; it is not a fixed 5555.
• A step failed: expand the failed step and read its log (or open the sidebar Logs page for the full record), fix the cause, and tap Retry installation.

Option 2: Manual commands (Termux)

Prerequisites:

1. Termux installed from GitHub (the Play Store version is crippled)
2. A network that can reliably access GitHub

1. Update Termux and install basic tools

pkg update
pkg upgrade -y
pkg install -y git proot-distro

2. Clone the NKAS repo

git clone https://github.com/megumiss/NIKKEAutoScript.git
cd ~/NIKKEAutoScript

3. Create the config file

cp config/deploy.template-docker-cn.yaml config/deploy.yaml

4. Install the NKAS image

proot-distro install megumiss/nkas:latest --name nkas

5. Start NKAS

proot-distro run -b "$HOME/NIKKEAutoScript:/app/NIKKEAutoScript" -w /app/NIKKEAutoScript nkas -- /usr/local/bin/python gui.py

PaddleOCR is unstable on ARM64 Linux; the more threads, the more likely it is to crash. If it crashes, set Instance → NKAS (⚙️) → Optimization Settings → OCR Threads to 1.

6. Open the NKAS WebUI

Open http://127.0.0.1:12271 in a browser.

If it is unreachable, Termux may be restricted in the background; allow it to run unrestricted.