Mega Man Battle Network 3: Implement New Game (#1198)

* Initializes MMBN3 world with empty files

* Adds item names to item dict

* Adds locations and names

* Adds skeleton of MMBN3Client. Mostly copy pasta from OOT

* Fixed some style and formatting

* More incremental Lua tests

* Adds all locations and checking to Lua connector

* Made class definitions for TextPet Parser

* Begun connecting item delivery system through lua and textpet

* Lua Connection can now send test items

* Item Delivery is now parameterized. Test command can send any chip

* Adds the ability to send non-chip items

* Fixes name errors in python client

* Fixes count for zenny, attempts to fix bugfrags

* Fixes an issue where you always received 255 bugfrags

* Converts zenny and bugfrag amounts to little endian bytecode

* Checks game state before sending chips

Adds debug option to display information overlayed on rom
Fixes chip indexing issue for chips with ids over 255
Minor text fixes

* Adds in some animation reset instructions during item get message

* Stores previously collected item index in save, re-sends missing items

* Adds title screen check before sending locations

Loading items from save could not be done via RAM. Had to be added in
assembly

* Adds progressive undernet check

* Added library for lzss decoding bits of rom

* More progress on parsing text events from ROM

* Adds a way to inject messages into ScriptArchive data structure and generate bytecode

* Adds Item definitions, passes to client

* Adds regions and item collection rules

* Touched up a few names and values that have changed in preparation for the final patching

* Modifying messages via item is now successful

* Added generate_output hook to generate ROM data

* Generates ROM successfully

* Fixes navi cust give index

* Whoops forgot to wrap this in brackets

* Injects extra scripts for undernet rankings

* Programs had ammount and color swapped

* Prompts the user for their username when connecting

* Adds flagClear to the list of commands to avoid overwriting

* Fixes message box crashes and several other multiworld issues

* Fixes IDs and names of several items and locations

* Added .gba to gitignore

* Fixes compatibility after recent rebase

* Fixes some locations and items that are otherwise unobtainable

* Attempts to make a working launcher in the installer

* Creates installer and fixes several inaccessible locations

* Many minor changes to items, locations, and requirements made during testing

* Adds an info page for MMBN3

* Fixes failing tests by removing duplicate IDs and properly marking progression items

* Accidentally forgot to un-remove the thing

* Whoops, changed this by accident

* Updates self.world references to self.multiworld

* Fixes imports to use from imports instead of using the namespace

* Removed some leftover merge artifacts from inno setup

* Puts back that darned signtool line again

* Adds Overworld Metro keys as items

* Adds TamaCode and puts shortcuts behind cyber passes

* Fixes Numberman code 16 check

* Fixes metro access logic and adds text to metro

* Reworks Lua to fix crashing when many items are queued

* Items for other BN3 games for different players are no longer given in the main player's ROM as well

* Fixes incorrect Item ID for ACDC Metro

* Fixes multi-box text messages

* Adds timer before sending an item

* Forgot to remove the second box of SubMems

* Updates patch and lua to prevent softlocks and crashes

* Adds options for extra undernet ranks, exclude jobs

* Extra GigFreez now gives 20 bugfrags

* Additional Progressive Undernets can no longer appear on the WWW Base

* Moves item signal byte to empty area of flags instead of end of RAM

* Adds Chocolate Shop locations and navi chips to fill them

* Fixes save crash, and added chocolates to lua

* Fixes chocolate stand selling out text, removes DrillMan cube in Undernet

* Replaces old messaging system with direct memory manipulation for receiving items

* Removes NDSPY requirements from MMBN3 by manually adapting the GBA's lz10 algorithm

* Fixes the names of Hospital-1 Locations

* Adds Canary Bit to avoid sending checks when title screen check fails

* Gaining a cybermetro pass will now open the shortcut immediately

* Randomizes the two accessible areas of Undernet 7, adds Hammer as item

* Adds new locations to connector lua

* Injects the name of the item into trade quests

* Fixes copy-paste error in docs

* Fixes merge artifacts and depracated code

* Nut-wafer stand now faces Lan the right way after buying

* Removes unused Goal Option and updates the readme to include most recent changes

* Touch-ups and formatting changes

* The Great Fillerization update. Dozens of items changed to Filler

* Replaces instances of Mega Man with MegaMan

* Update worlds/mmbn3/docs/en_MegaMan Battle Network 3.md

Co-authored-by: el-u <109771707+el-u@users.noreply.github.com>

* Update worlds/mmbn3/__init__.py

Co-authored-by: el-u <109771707+el-u@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: el-u <109771707+el-u@users.noreply.github.com>
Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com>

* Changes code ordering to suit base class's

* assert_generate now checks for roms. Minor text fixes

* Makes player specific frequency and excluded location options

* Apply suggestions from code review

Co-authored-by: el-u <109771707+el-u@users.noreply.github.com>

* Addresses suggested changes from PR review

* Replaces ndspy lz10 with MIT-compliant nlzss lz10

* apworld compatibility fix for mmbn3_options from utils

* Addressing more comments by el-u

* APworld will now pull patch from zip folder

* Apply suggestions from code review

Co-authored-by: el-u <109771707+el-u@users.noreply.github.com>

* Cleaned up comments for progressive undernet ROM function, moved index list to field to avoid re-initializing

* Removes improper player-indexed location/item dicts, replaces with world member variables

* Avoids redefining list in progressive undernet ROM function

* Filler items can no longer be generated beyond their specified amounts

* Fixes list copying issue with item frequencies

* Adds BN3 Client Generation back into Launcher settings

* Fixes typos causing huge problems

* Fixed non-relative import for apworld

* Removes custom enum implementation that broke pickle

* Displays message when attempting to load an incorrect ROM, will not attempt to patch it

* Filler items can now only be placed once

* Changes path in setup doc to match Lua path changes

* Fixes file extension for MMBN3 file

* Replaces magic number with reference to value in NetUtils

* Moves victory rules to set_rules. Removes commented out code

* Rewrites Lua script to send block of memory

* Fixes off-by-one error in sending bytes for locations

* Fixes issue with invalid characters in text parsing, and WWW monitor text box parsing

* Moves trade text injection to init so it has access to options

* Attempts to split the text boxes for hinted items

* Trade checks now provide hints if the option is set for them

* Fixes escape character issue for BizHawk 2.9.1

Something in Bizhawk lua parsing changed to dislike the escaped tilde.
I'm not even entirely sure why it was escaped in the first place, but
this should fix the compatibility of it.

* Re-adds desk check that it turns out actually does exist

* Updates requirements to mention bizhawk 2.7 instead of 2.3.1

* Fixes off-by-one error in command byte counts

* Fixes program color indices

* Fixes newline PEP violations

* Reverts an accidental whitespace change made to launcher.py

* Fixes URL formatting on link to settings from setup guide

Co-authored-by: Zach Parks <zach@alliware.com>

* Splits several lines in the readme to avoid excessive length

* Fixes formatting and (hopefully) reduces cringe of joke in setup doc

* Removes unnecessary constructor

* Changes item frequency generation to avoid reusing the same references

Co-authored-by: Zach Parks <zach@alliware.com>

---------

Co-authored-by: el-u <109771707+el-u@users.noreply.github.com>
Co-authored-by: SoldierofOrder <107806872+SoldierofOrder@users.noreply.github.com>
Co-authored-by: Zach Parks <zach@alliware.com>

worlds/mmbn3/docs/en_MegaMan Battle Network 3.md

@@ -0,0 +1,74 @@
+# MegaMan Battle Network 3
+
+## Where is the settings page?
+
+The [player settings page for this game](../player-settings) contains all the options you need to configure and
+export a config file.
+
+## What does randomization do to this game?
+
+Items which the player would normally acquire throughout the game have been moved around. Logic remains, so the game is
+always able to be completed, but because of the item shuffle, the player may need to access certain areas before they
+would in the vanilla game.
+
+The game begins in "Open Mode", in a story state just before leaving for the WWW Base. All story progress leading up to
+that point has been auto completed. You will be given a Style Change upon starting, but will
+have default MegaMan equipped, you can switch to your new style if you want through the Navi menu.
+
+Higsby's Chip Trader has been replaced with a shop interface where you can pay 500z to access the next item in the
+trader sequence.
+Dialog has been rewritten for both the Trader and the hat kid next to the trader to explain it.
+
+The Nut-Wafer Chocolate Stand in the Yoka Metro has been replaced with a system for trading BugFrags for items.
+Dialog has been rewritten to give it a story reason for accepting BugFrags.
+
+The Secret Area is unlocked from the start, since the Library is filled automatically. Jacking Out has been enabled
+in the Secret Area.
+
+## What is the goal of MegaMan Battle Network 3 when randomized?
+
+Defeat Alpha on the WWW Base. You will not be able to access the Island until you have acquired the item `GigFreez`,
+which will be the eight item in the `progressive-undernet` item sequence. You will need to acquire Undernet Ranks
+10, 9, 8, 7, 3, 2, and 1 before acquiring `GigFreez`
+(Note: The skipping of 6-4 is intentional. They do not exist in the base game.)
+
+## What items and locations get shuffled?
+
+Locations in which items can be found:
+- All Blue and Purple Mystery Data.
+- The rewards from all available Jobs (Note: The four "Tora" jobs are story progress, and therefore have 
+been already completed). 
+- All overworld item pick ups, including Trades and Quizzes with NPCs
+- 31 Items from the Numberman Lottery Trader (which have been changed to require Zenny instead of lotto numbers)
+- 32 Items from the Nut-Wafer Chocolate stand in Yoka Metro Station (which have been changed to require BugFrags 
+instead of Zenny)
+
+Items that are shuffled:
+- All of the original rewards from above (Note: Certain common chips and low amounts of Zenny have been classified
+as "filler" and might be replaced with progression items)
+- All four Cybermetro passes, normally obtained through story progression
+- Eight Progressive Undernet Ranks, normally obtained through story progression
+- Several chips required for specific Jobs or Trades that would normally be unobtainable without RNG
+- The NaviCust "Press" program, normally obtained through story progression
+- Two ExpMems and ModTools for the Navi Customizer, normally obtained through story progression
+- Higsby's `OrderSys`, which will enable access to the Chip Order System
+
+## What items are _not_ randomized?
+Certain Key Items are kept in their original locations:
+- All four of the ID Keys in the WWW-Comp machines on the WWW Base
+- Items in Undernet 7 locked behind post-game progression gates, such as beating Serenade or gathering all chips
+
+## Which items can be in another player's world?
+
+Any shuffled item can be in other players' worlds.
+
+
+## What does another world's item look like in Mega Man Battle Network 3?
+
+Item pickups all retain their original appearance. Text Boxes for accessing an item or given in dialog will mention
+what item and what player is receiving the item
+
+## When the player receives an item, what happens?
+
+Whenever you have an item pending, the next time you are not in a battle, menu, or dialog box, you will receive a
+message on screen notifying you of the item and sender, and the item will be added directly to your inventory.

worlds/mmbn3/docs/setup_en.md

@@ -0,0 +1,79 @@
+# Setup Guide for MegaMan Battle Network 3 Archipelago
+
+## Important
+
+As we are using Bizhawk, this guide is only applicable to Windows and Linux systems.
+
+## Required Software
+
+- Bizhawk: [Bizhawk Releases from TASVideos](https://tasvideos.org/BizHawk/ReleaseHistory)
+  - Version 2.7.0 and later are supported.
+  - Detailed installation instructions for Bizhawk can be found at the above link.
+  - Windows users must run the prereq installer first, which can also be found at the above link.
+- The built-in Archipelago client, which can be installed [here](https://github.com/ArchipelagoMW/Archipelago/releases)
+  (select `MegaMan Battle Network 3 Client` during installation).
+- A US MegaMan Battle Network 3 Blue Rom
+
+## Configuring Bizhawk
+
+Once Bizhawk has been installed, open Bizhawk and change the following settings:
+
+- Go to Config > Customize. Switch to the Advanced tab, then switch the Lua Core from "NLua+KopiLua" to
+  "Lua+LuaInterface". This is required for the Lua script to function correctly.
+  **NOTE: Even if "Lua+LuaInterface" is already selected, toggle between the two options and reselect it. Fresh installs** 
+  **of newer versions of Bizhawk have a tendency to show "Lua+LuaInterface" as the default selected option but still load** 
+  **"NLua+KopiLua" until this step is done.**
+- Under Config > Customize > Advanced, make sure the box for AutoSaveRAM is checked, and click the 5s button.
+  This reduces the possibility of losing save data in emulator crashes.
+- Under Config > Customize, check the "Run in background" and "Accept background input" boxes. This will allow you to
+  continue playing in the background, even if another window is selected, such as the Client.
+- Under Config > Hotkeys, many hotkeys are listed, with many bound to common keys on the keyboard. You will likely want
+  to disable most of these, which you can do quickly using `Esc`.
+
+It is strongly recommended to associate GBA rom extensions (\*.gba) to the Bizhawk we've just installed.
+To do so, we simply have to search any GBA rom we happened to own, right click and select "Open with...", unfold
+the list that appears and select the bottom option "Look for another application", then browse to the Bizhawk folder
+and select EmuHawk.exe.
+
+## Configuring your YAML file
+
+### What is a YAML file and why do I need one?
+
+Your YAML file contains a set of configuration options which provide the generator with information about how it should
+generate your game. Each player of a multiworld will provide their own YAML file. This setup allows each player to enjoy
+an experience customized for their taste, and different players in the same multiworld can all have different options.
+
+### Where do I get a YAML file?
+
+You can customize your settings by visiting the 
+[MegaMan Battle Network 3 Player Settings Page](/games/MegaMan%20Battle%20Network%203/player-settings)
+
+## Joining a MultiWorld Game
+
+### Obtain your GBA patch file
+
+When you join a multiworld game, you will be asked to provide your YAML file to whoever is hosting. Once that is done,
+the host will provide you with either a link to download your data file, or with a zip file containing everyone's data
+files. Your data file should have a `.apbn3` extension.
+
+Double-click on your `.apbn3` file to start your client and start the ROM patch process. Once the process is finished
+(this can take a while), the client and the emulator will be started automatically (if you associated the extension
+to the emulator as recommended).
+
+### Connect to the Multiserver
+
+Once both the client and the emulator are started, you must connect them. Within the emulator click on the "Tools"
+menu and select "Lua Console". Click the folder button or press Ctrl+O to open a Lua script.
+
+Navigate to your Archipelago install folder and open `data/lua/connector_mmbn3.lua`.
+
+To connect the client to the multiserver simply put `<address>:<port>` on the textfield on top and press enter (if the
+server uses password, type in the bottom textfield `/connect <address>:<port> [password]`)
+
+Don't forget to start manipulating RNG early by shouting during generation:
+
+```
+JACK IN!
+[Your name]!   
+EXECUTE!
+```