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) or Windows 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 or 0x80370102. 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 to C:\Users\John, typing cd mnt/c/Users/ and pressing Tab 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:\ or D:\), 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 directory
    • cd /mnt/c will take you to your Windows C: 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, type ls -l
  • touch test.txt will create a blank file called test.txt in your working directory
  • mv test.txt file.txt will rename a file called test.txt to file.txt in your working directory
  • rm file.txt will remove a file called file.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 called folder 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 update apt-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.
  • 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 typing java -jar pkc-mms-rando*.jar -h, but bear in mind that -d and -D are already provided when running the program using run.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.