Skip to content

Usage Guide Physical Device

Megumi edited this page Aug 28, 2026 · 7 revisions

Using NKAS - Android Physical Device

⚠️ Risk notice (read first)

  • Temporary (3-hour) bans have been reported. Don't fear it if you use it; don't use it if you fear it; don't complain if you get banned
  • Not recommended on your main phone
  • Resolution mode changes the system resolution and may cause issues; virtual display mode is not affected

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; suspected of being detected and banned)

  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 (⚙️) → Emulator/Device 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

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.

Clone this wiki locally