The aim of this page is to help the reader set up Bizhawk for Multiworld. Multiworld is a co-op mod for the OoT Randomizer. Players have their own inventory and their own world. Also, player-specific items are mixed between the worlds. For example, if you obtain an item in your world, it could either stay with you or get sent to another player. Everyone participating will be playing different intermingled seeds.
As an example, there could be a scenario where Player 1 can only advance in their own world based on something Player 2 does. Once Player 2 finds the Megaton Hammer belonging to Player 1, Player 1 will automatically receive it. Every world is linked together.
In order to link everyone's worlds together, players need to make use of "lua scripts". As written, these are only compatible with Bizhawk, however the ModLoader64 devs have made a copy which is compatible with ModLoader64. (For assistance with ModLoader64, please join their Discord.) Support for other emulators, as well as console support, is planned for future releases.
Generating the Seeds
Using the Webpatcher
Start off by going to the Webpatcher and set up the settings you want for the seed. On the Rom Options tab change the Player Count to however many people will be playing. Once you're done, generate the seed.
After you have generated the seed, share the URL with your partners and have everyone choose a different Player ID. Then continue patching the rom as you would normally (don't forget cosmetics and sfx). Each player should have their own Randomizer ROM, with the formula OoT_SeedID_SettingsHash_W0P0 with the W0 and P0 being world count and player ID respectively.
Using the Offline Version
Generating a ROM using an offline build works a little differently. After choosing the settings you wish to play with, go to the ROM Options tab and set Generate From Seed. Choose Patch File as your Output Type and change the Player Count to however many people will be playing. Then hit Generate!.
Send the patch file (.zpfz) to your partners and have them set Generate From File. The Output Type should be Compressed [Stable] now, and everyone should choose a different Player ID. Select the patch file and hit Generate! (don't forget to set cosmetics and sfx). Each player should have their own Randomizer ROM, with the formula OoT_SeedID_SettingsHash_W0P0 with the W0 and P0 being world count and player ID respectively.
Note: if your partners don't have the offline build they can also patch the rom using the website. Make sure to set Generate From File and select your patch file (.zpfz).
There are several reasons why someone might want to generate a ROM using an offline build. For example, some builds might have features that are not available on the website build (yet), like additional Entrance Randomizer settings. Generating from an offline build also lets you play with your own custom patches.
Installing Multiworld and Bizhawk
The Recommended Method
Press Windows+R to open the Run dialog box, and then type "powershell" in the text box. Once you have your PowerShell window open, copy-paste this in:
cd $env:userprofile\downloads;
Set-ExecutionPolicy Bypass -Scope Process -Force;
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072;
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/TestRunnerSRL/bizhawk-co-op/dev/bizhawk-co-op.ps1'))
From here, the PowerShell is getting you 99% of the way done: it will create a new Bizhawk 2.3 install in your downloads folder and place everything for you. Say yes when PowerShell prompts you to install the bizhawk_prereqs.exe file. Once PowerShell is done, you can move the Bizhawk 2.3 folder somewhere else if you wish. Afterwards, open up the Bizhawk 2.3 folder it created and launch EmuHawk.exe.
The Alternate Method
Download the Custom Bizhawk Installer
First, you must download the Multiworld script from TestRunner's GitHub page. When you download this, extract its contents to its own folder - it will be creating a new Bizhawk install for you to use, so you must keep it separate. Note: Whenever there is an update to the Multiworld script, everybody playing must update to the latest version.
Running the Custom Bizhawk Installer
Once you have the contents extracted to its own folder, locate the bizhawk-co-op.ps1 file. Right Click and select Run with PowerShell.
If Powershell prompts you for permissions, say yes to all. From here, the Powershell is getting you 99% of the way done: it will create a new Bizhawk 2.3 install and place everything for you. Once Powershell is done, open up the Bizhawk 2.3 folder it created and launch EmuHawk.exe. Note: It is recommended you delete everything outside of the Bizhawk 2.3 folder that was created. These files are no longer needed and only add confusion.
Powershell Permissions
You may need to enable executing Powershell scripts without requiring the script to be digitally signed. Open Powershell from the Start Menu by right clicking it and selecting "Run as Admin". Click the "Yes" button to allow Powershell to run as Administrator. Type Set-ExecutionPolicy Unrestricted and press Enter once, type Y then press Enter again. The Powershell script should now run.
Configuring Bizhawk for Multiworld
Bizhawk Settings
There are a few things you need to do once you've got the emulator running. The very first thing is go to Config -> Customize and navigate to the Advanced tab. At the bottom, there is an option for Lua Core; select Lua+LuaInterface and hit OK. While on the Advanced tab, you should also check the box for AutoSaveRAM and set it to a reasonable time, such as 60-180 seconds (keep in mind that setting this too low could increase lag and decrease overall emulator performance). This will allow Bizhawk to write your in-game save to your drive. This is NOT a form of save state - it simply periodically creates/updates a file on your hard drive with your in-game save data, and is wonderful for mitigating the effects of crashes. In the event of a crash (or if you open TAStudio by accident) DO NOT RELOAD THE ROM! DO NOT RELOAD THE ROM! Doing so will overwrite your backups, meaning that your save files will be gone. To recover your save file follow the instructions over here.
In the General tab of the Customize menu, tick the boxes for "Accept background input" and "Run in background" – this will allow Bizhawk to keep accepting controller inputs when you tab over to your tracker or notes and prevent the emulation from pausing (which will disconnect you). Clear your hotkeys by going to Config -> Hotkeys, and at the bottom click Misc and Clear All.
Controller Settings
The next step is to set your controller up. Your controller configuration will vary based on what controller you are using; for Bizhawk to enable the Controller menu, you must have a ROM loaded. For a smooth controller experience, you must unbind the first 4 binds in Config -> Controller such that it looks like this:
You'll then have to bind your analog stick in the Analog tab of your controller config and adjust your sensitivity and deadzones to your preference. Additional info on controller setup can be found in Step 6 of the Bizhawk Guide.
Video Settings
You can fix how your game looks by going to Config -> Cores -> N64 Video Plugin Settings. In here, change your resolution so that it runs smooth. Multiworld will drop your performance, so keep that in mind. The recommended video plugin is GLideN64. (This is not the same plugin as Glide64!)
Starting the Multiworld Session
Opening the Lua Console
Once you have your emulator set up to run how you are comfortable with, its time to move to the Lua console. Go to Tools -> Lua Console, and a separate window will open up. This window must remain open at all times during a Multiworld. In the Lua Console, go to Settings and checkmark the Disable Scripts on loads.
This is the last of the settings changes you have to do. If you want Bizhawk to retain these settings changes for the next time, go to Config -> Save Config. Once you have these steps done, you MUST close your emulator and reopen it for this change to take effect. Close out of Bizhawk, and then reopen it and the Lua Console. Sometimes this will not be enough and you will still get an error trying to load the Lua file. In that case reboot your entire computer.
If for some reason you do not have your Multiworld ROM open, you must do so now.
From here in the Lua Console, Open Script and locate the bizhawk co-op.lua file in the Bizhawk 2.3 folder. Once you have that done, a red square will appear in the console; double click it and a new window will open up.
This window must also stay open at all times.
Rooms
The Lua Console Script is where you set up a room and join rooms.
If you are the Host: You must port forward. How you do this varies on what brand your router is. Instructions on how to do this can be found by Googling your brand/model of router. You'll want to use a port between 49152 and 65535. We highly recommend using the default port, 50000. You'll also want to ensure you're forwarding the TCP protocol as that is the protocol Multiworld uses. Most other games you have port forwarded in the past likely were using the UDP protocol.
Once that is done, in the Bizhawk Co-op window the Host must set their name, password, and the port that was forwarded, along with setting the game script to Ocarina of Time. Don't set the IP address. Hit Create Room and tell the people joining the Room Name (= your name), password, and port. (It is not recommended to use your own personal password here, as it is shared with the group. Use something that will prevent random people from joining your room, but not something that will compromise your own security.)
If you are Joining and the Host has set up the room: hit Refresh in the Bizhawk Co-op window and select the Host's Room from the dropdown bar. When you input your username, keep in mind the game will use this to display who got what item for everyone playing. It will max out at 8 characters, even if you input more. Fill in the password and port number the Host gave you and select the Ocarina of Time Game Script and hit Join Room.
You can also select a player number when both hosting and joining a room. This is non-mandatory, and player numbers will be automatically selected if non are entered. This also does not need to match the world number chosen when patching your ROM file. If you do select a player number, and that number is already filled in that room, you will be unable to join.
Play Some Multiworld!
Go and have fun with new or old friends! If you are part of the Ocarina of Time Randomizer Discord, you can assign the Multiworld role to yourself by going to the #chat-bot channel and typing !role Multiworld - this will allow you to receive pings in the server where there are announcements from the Devs or folks are looking for players. You can also visit #multiworld-planning to look for additional players. It is highly recommended that you use one of the Trackers so that you don't accidentally leave those new friends out to dry if you miss a check. Map Trackers such as 2deep4real's Web Tracker or Hamsda's Map and Item Tracker package for EmoTracker are highly recommended.
Troubleshooting
Installation Issues (Applies to both the Recommended and Alternate Methods)
Windows 7
If you are running Windows 7 you will need to enable remote Powershell script execution, and make sure Powershell is updated.
First, go to the Installing Powershell page and navigate to the download page for the the latest Windows 7 SP1 Powershell version. At the time of writing it is WMF 5.1. The file on the download page you want to download is named similar to Win7AndW2K8R2-KB3191566-x64.zip. Run the .msu file inside of the zip file and it should update Powershell.
Anti-Virus
Another issue that can occur while running the Powershell script is your anti-virus deleting the files it downloads. The BizHawk Prerequisites often gets marked as suspicious due to it being an installer that runs more installers. We can't give a detailed guide on how to exclude a folder in every anti-virus software, but search Google with a query like Exclude Folder <your_anti-virus_name> and you should find a guide on their official site explaining how to do so. Exclude the folder that has the Powershell script in it and now you should be able to run it without the downloaded files getting deleted.
Common Error Messages
These are the most common errors that pop up that have known solutions. If none of these solve the problem, try rebooting your computer again afterwards to ensure any new configurations are fully loaded.
NullHawk Does Not Implement Memory Domains
You must load the ROM before activating the Lua scripts.
Error 401
This generally means that either the password entered was incorrect, or that the room name already exists. Also, avoid special characters like spaces in the room name. We recommend using letters (no accents) and numbers only.
This ROM is not compatible with this version of the co-op script.
Unable To Find Domain: CARTROM
You are using the A Link to the Past LUA script. Choose Ocarina of Time in the dropdown instead.
Dynamic Libraries Not Enabled
You did not set the Lua Core setting properly. Remember to restart Bizhawk after changing it.
Unprotected Error in Call to LUA API
This is a general error that pops up randomly. You need to ensure all copies of Bizhawk are closed properly. The easiest way to ensure this is by rebooting your computer.
Connection Failed: Timeout
There are several reasons this can happen, all of them being various methods of misconfiguration.
First, the host must have the port being used forwarded if not using Hamachi. Your private IP address that you forward the port to can change for various reasons. Always ensure that the router is pointing to the right computer with the port forwarding options. The host must also not have pings blocked in their router settings. This setting can be found under many names depending on the router.
Everyone playing must have the Bizhawk emulator allowed through their firewall.
The above Bizhawk configuration options are not optional. If you do not configure the emulator properly you will be unable to stay connected to each other.
Miscellaneous Issues
A Specific Item Failed to Transfer
Items can be retrieved by having the receiving player enter a line of code into the Lua console, though it is best to avoid this situation entirely if possible. This frequently occurs if a player continues while one or more other players are disconnected from the room. To prevent this, always ensure everyone is connected before collecting any item.
Go to this website (made by pidgezero_one) and select option 2. Locate the code for the missing item and follow the instructions there to retrieve the item. If the layout looks wrong, press ctrl+F5 to fix it.
Help! My emulator crashed!/I accidentally opened TAStudio and got a black screen!
First of all, DO NOT RELOAD THE ROM! DO NOT RELOAD THE ROM! Doing so will overwrite your backups, meaning that your save files will be gone. To recover your save files follow these instructions.
- In your Bizhawk folder navigate to
\N64\SaveRAM. - Identify the
SaveRAMandAutoSaveRAMfiles corresponding to your seed. Sorting by date may help. Note that theAutoSaveRAMfiles will only exist if you've enabled that beforehand. - Optional: manually make a backup of these files somewhere on your pc.
- Delete the
SaveRAMfile and renameAutoSaveRAMto take the place of theSaveRAMfile you've just deleted. - Now you can safely load your seed again and continue playing.
A Player Forfeits without Finishing
If a player forfeits their world, the game can continue without them by entering code lines into the Lua console to retrieve the lost items for the remaining players. Upload the multiworld spoiler log on this site (made by pidgezero_one) and follow the instructions there. If the layout looks wrong, press ctrl+F5 to fix it.
LUA Console Window Too Small
If your window for the LUA connection console is too small and the elements are overlapping, you need to change your DPI settings. Right click EmuHawk -> Properties -> Compatability -> High DPI scaling override, change to "System (Enhanced)".
Multiworld Without Port-Forwarding or Bizhawk
Hamachi
If nobody in your multiworld group can port-forward for whatever reason, and you cannot get someone who can to join, then there is a program you can use: Hamachi. Let me preface this by saying that Hamachi basically 'tricks' your computers to believe that you are all connected via LAN.
To start, download Hamchi [here] and install it. Create an account, and go to System > Preferences > Settings to make sure that 'Encryption' is enabled. Then, click on the power button to go online.
Hosting
If you're hosting, then click Network > Create a new network. Give it a unique name and password, making sure that nobody other than the people you're playing with find out this information. After this, you'll see it pop onscreen:
To join an existing network, click Network > Join an existing network. Type in your friend's network ID and the network's password.
Once you're all connected in the network, you can start the multiworld.
Right click on the address above your nickname, and click 'Copy IPv4 address' and share it with the people joining you:
Then, start up the Bizhawk co-op lua script. Set 'Rooms' to '(Custom IP)', Set your Username and Password as usual, and the game script to Ocarina of Time.
Joining
Then, start up the Bizhawk co-op lua script. Set 'Rooms' to '(Custom IP)' and paste the IPv4 the host gave you into the 'Host IP' bar. Set your Username and Password as usual, and the game script to Ocarina of Time.
Now you should be ready to start. As usual, if you have any more problems, seek advice within the OoTR Discord Server.
Security Awareness
Be careful with who you give permission to join your network to. Using Hamachi is like letting everyone using it with you use a computer on the same network as yours.
Hamachi Request Timed Out
Follow these steps to ensure Hamachi is allowed through your firewall. Both the Host and the clients connecting to the host should do this.
Playing over LAN
If you're playing over a LAN network, then all you need to do is set the 'room' to (Custom IP), type the LAN's Ipv4 into the 'host IP' field, and give yourself a username. Leave the password field blank.
Play Without Bizhawk
While Bizhawk is the officially supported emulator for multiworld, it is known to be a resource-intensive emulator in addition to being Windows only. If using Bizhawk is impossible for any reason, try the emulator ModLoader64 (Windows and Linux compatible), as DemoXin has modified the multiworld script to work with it. This method does not require a host. Modloader64 is also the only way to play Ocarina of Time Online, which allows players to see each other in the world, and also supports other various features. As we do not officially support this emulator or any of their paks, we kindly refer you to their Discord for all issues and support.