PKsinew

PKsinew is a companion app/frontend launcher for Gen 3 Pokémon games that lets you track your progress across all 5 GBA games.

It allows you to:

• Access Sinew default start+select
• Gain achievements and rewards
• Handle mass storage & transferring Pokémon between games
• Access mythical rewards
• Explore re-imagined abandoned features from the original games
• Export save data to readable json file for other projects

PKsinew supports Windows, macOS, and Linux, and works best with a controller for seamless gameplay tracking.

Devlog / Updates: Sinew Devlog

Discord: Sinew Discord

---

Table of Contents

1. How to Use
   • Add ROMs
   • First-time In-App Setup
   • Tips & Notes
2. How to Build
   • Install Python 3
   • Install Dependencies
   • Build Executable
   • Dev Environment
3. Troubleshooting

---

How to Use

If you downloaded a release, you do not need Python or any dependencies. Just follow these steps:

Add ROMs

1. Place your legally obtained ROMs in the roms folder.

• Supported formats: .gba, .zip, .7z
• Supported games:
  • Pokémon Ruby
  • Pokémon Sapphire
  • Pokémon Emerald
  • Pokémon FireRed
  • Pokémon LeafGreen

---

First-time In-App Setup

1. Map your controller buttons in Settings
2. Enable external providers if using retroarch or a retro handheld, or add ROMs to the roms folder
3. Restart the app if ROMs are added after booting
4. Start playing — achievements and tracking begin automatically

---

Tips & Notes

• Save files are stored in the saves/ folder — back these up regularly
• Logs are written to sinew.log in the root folder — include this if reporting a bug
• Controller is highly recommended but keyboard works too

---

Building

If you want to build PKsinew yourself, follow these steps:

Install Python 3

| Platform | Instructions | | ----------- | ----------------------------------------------------------------- | | Windows | Download Python 3.12 | | macOS | Download Python 3 | | Linux | See below |

Windows — Important Installation Steps

1. Download Python 3.12 from the link above (3.12 is recommended for best compatibility)
2. Run the installer
3. On the first screen, check the box that says "Add Python to PATH" — this is critical. If you skip this, commands won't work
4. Click Install Now and let it finish
5. Open PowerShell (search for it in the Start menu) and verify it worked:

python --version

You should see something like Python 3.12.x. If you get an error, you likely missed the PATH checkbox — re-run the installer and check it.

macOS

Download Python 3 and follow the standard installer.

Verify installation:

python3 --version

Linux

sudo apt install python3 python3-pip

Verify installation:

python3 --version

Install Dependencies

All commands from this point on need to be run from inside the PKsinew folder.

With your terminal open in the PKsinew folder, run:

Windows (PowerShell):

pip install -r requirements.txt

macOS / Linux:

pip3 install -r requirements.txt

If you get a permissions error on macOS/Linux, try:

pip3 install --user -r requirements.txt

This will install all required packages (Pillow, NumPy, Pygame, requests, etc.) automatically.

Build Executable

1. Run the build command from the project root:

  pyinstaller --clean PKsinew.spec

2. The built app will appear in the dist/ folder.

---

Dev Environment

You can run PKsinew directly from source for development and testing. From the project root (not src/), run:

Windows (PowerShell):

python -m src

macOS / Linux:

python3 -m src

PKsinew is configured to know when it's being run in dev mode and will find all resource folders automatically. Do not cd into src/ and run a file directly — the entry point is src/__main__.py and it must be launched as a module from the project root.

Troubleshooting

"python is not recognized" error on Windows

You missed the "Add Python to PATH" checkbox during installation. Re-run the Python installer, choose "Modify", and enable the PATH option. Or uninstall and reinstall with the checkbox checked.

"pip is not recognized" on Windows

Same cause as above — Python isn't on your PATH. Re-run the installer with the PATH option enabled.

Black screen / app won't start

Make sure all dependencies are installed. See above for running pip install -r requirements.txt.

Game not detected

Make sure your ROM is supported. PKsinew is designed to work with the GBA Pokemon games only.

Linux: No module named 'pygame.font' / 'pygame.mixer'

Try to install pygame through your package manager, and retrying from Build Executable. This may be called "python3-pygame" or "python-pygame", depending on your distro.