Getting Started - TheG-Meister/pkc-mms-rando GitHub Wiki
A detailed guide on how to set up pkc-mms-rando! Follow this guide through from top to bottom to setup the program and start making randomisers.
Windows 10 & 11 - Windows Subsystem for Linux (WSL)
Windows Subsystem for Linux (WSL) allows an instance of Linux to run on a Windows machine. Linux is necessary to turn disassemblies into ROMs, so this process is adapted to carry out the whole randomisation process through Linux.
Full setup instructions for WSL can be found here.
- If on Windows 10, update your PC. The following WSL install process is possible on all Windows 11 versions, but only more recent versions of Windows 10
- Right click the Start button, and select
Command Prompt (Admin)
orWindows PowerShell (Admin)
- In the window, type
wsl --install
and press Enter - Once the install process has finished, restart your computer
- Upon logging in, a window named
Ubuntu
should appear and continue installing - This sometimes hits an error with code
0x80070003
or0x80370102
. If this happens, you may need to enable CPU virtualisation in your computers BIOS settings. You'll have to figure out how to do this for your machine, but the option is often found under CPU settings. Once you have done this, restart your computer again and launch Ubuntu from the Start Menu.
Using a command prompt
This section will provide a brief introduction to using a command line. These commands and tips will get you started using pkc-mms-rando, but for a more well rounded introduction, check out the following guide from Ubuntu.
If this is your first time encountering a command prompt, they aren't as scary as they look!
- Commands are run by typing into the box and pressing
Enter
- The
_
character is your cursor, which you can move left and right using the arrow keys - If you need to clear the text on the current line, press
Ctrl + C
Ctrl + C
will also stop an executing command. Be careful with this, as often programs are working away quietly in the background. Stopping them early can break things!- Considering this is the shortcut for copying on Windows, you can highlight text from the command line using Left Click + drag, then press
Ctrl + C
to copy - To paste text into the prompt, simply Right Click
- The up arrow will scroll through your previously entered commands. Continuing to press it will scroll through your command history
- When the command line itself is ready to accept a new command, it will display something like
user@DESKTOP-1234ABC:~$
- If there is a space in your argument,
"quote"
it! Single and double quotes both work - Pressing
Tab
will attempt to autocomplete the argument you are writing. This includes file paths - if you want to change your working directory toC:\Users\John
, typingcd mnt/c/Users/
and pressingTab
will fill in your username, whether it is John or not!
An essential part of using a command prompt is changing your working directory.
- When you start a command prompt, your working directory starts as the home directory for your user. This is abbreviated as
~
and shown at the end of the command prompt -~$
- The absolute file path of this directory is
/home/user/
, where user is your username - While absolute file paths in Windows start with a drive letter (eg.
C:\
orD:\
), the root directory in Linux is/
. Starting any file path with this will make the path absolute instead of relative - You can change your working directory by typing
cd
followed by a relative or absolute file path (and pressing Enter)cd /
will take you to the root directorycd /mnt/c
will take you to your WindowsC:
drive- Typing
cd "Program Files"
from here will then move you into your Program Files folder
Commands default to operation within your working directory. Here are some helpful examples:
- You can print your working directory by typing
pwd
- To check the contents of your working directory type
ls
. If you prefer a vertical layout with more details, typels -l
touch test.txt
will create a blank file calledtest.txt
in your working directorymv test.txt file.txt
will rename a file calledtest.txt
tofile.txt
in your working directoryrm file.txt
will remove a file calledfile.txt
in your working directory. WARNING - there is no Recycle Bin in Ubuntu. Once you remove a file, it is gone forever!mkdir folder
will make a directory calledfolder
in your working directory
Ubuntu Setup
- Once Ubuntu has finished installing, follow the setup instructions by providing a Username and Password
- The password prompt won't display what you are typing on screen, but it is listening
- Keep your password safe, as resetting it could be complicated!
- Type
sudo apt-get update
and type in your password. This will updateapt-get
, the program which installs other programs! - Finally, type
sudo apt-get upgrade
and type in your password to finish the update process. This will allow the installation of all additional dependencies
Now you have a functional instance of Ubuntu, you'll need to follow all the steps below to install the rest of the dependencies within it and run pkc-mms-rando.
Ubuntu
Now whether you're on a Windows computer or an Ubuntu computer, you have access to a Bash command line. This will be used for the majority of the remaining instructions.
The following sections combine instructions for installing a pokecrystal disassembly, installing RGBDS and pkc-mms-rando specific setup.
Dependencies
In order to perform the remaining steps below, you'll need some additional programs. These are:
make
gcc
git
bison
pkg-config
libpng-dev
openjdk-17-jre-headless
If you've just installed WSL, you'll need all of these! Thankfully it's easy to install all of them with a single command:
sudo apt-get install make gcc git bison pkg-config libpng-dev openjdk-17-jre-headless
Working directory setup
Next, we'll make a directory and download some extra necessary files.
- Download a pkc-mms-rando release - the latest release will contain the most features. Select the zip file to download (not the source code!) and extract it somewhere on your file system.
- Change the working directory of Ubuntu to the extracted folder.
- If you need to get to the Documents folder in Windows, type
cd /mnt/c/Users/user/Documents/
, replacing user with your username - To get to the Desktop folder, type
cd /mnt/c/Users/user/Desktop
, replacing user with your username - You'll know you're in the right place if you type
ls
and see the pkc-mms-rando jar,README.md
,LICENCE.txt
and at least one.sh
script listed.
- If you need to get to the Documents folder in Windows, type
- Clone a pokecrystal disassembly into this folder. Disassemblies verified to work with the version you are using can be found in the project's
README.md
, or on the home page of pkc-mms-rando for the latest version. All of these come with their own download instructions! - Rename the folder you just downloaded to
input
- Run
git clone https://github.com/rednex/rgbds -b v0.5.2 --depth=1
- Run
sudo make install -C rgbds
Running pkc-mms-rando
The final step is running the randomiser!
- Change the working directory of your command line to your pkc-mms-rando folder
- Type
bash run.sh
and append any randomiser arguments, such as--warps
or--music-pointers
. You can get a list of all command line options by typingjava -jar pkc-mms-rando*.jar -h
, but bear in mind that-d
and-D
are already provided when running the program usingrun.sh
- Wait a few minutes while the program runs. When it is done, you should see a
.gbc
file appear in the pkc-mms-rando folder
Congrats! Test your ROM to make sure the randomiser worked - sometimes it spits out an error before running, and subsequently just creates a vanilla ROM. The next time you want to make another randomiser, just follow the steps in this section.