Super Mario land 2: implement new game

worlds/marioland2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022-2023 Alex "Alchav" Avery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

worlds/marioland2/client.py

@@ -0,0 +1,202 @@
+import base64
+import logging
+
+from NetUtils import ClientStatus
+from worlds._bizhawk.client import BizHawkClient, BizHawkClientContext
+from worlds._bizhawk import read, write, guarded_write
+
+from .rom_addresses import rom_addresses
+
+logger = logging.getLogger("Client")
+
+BANK_EXCHANGE_RATE = 20000000000
+
+
+class MarioLand2Client(BizHawkClient):
+    system = ("GB", "SGB")
+    patch_suffix = ".apsml2"
+    game = "Super Mario Land 2"
+
+    def __init__(self):
+        super().__init__()
+        self.locations_array = []
+
+    async def validate_rom(self, ctx):
+        game_name = await read(ctx.bizhawk_ctx, [(0x134, 10, "ROM")])
+        game_name = game_name[0].decode("ascii")
+        if game_name == "MARIOLAND2":
+            ctx.game = self.game
+            ctx.items_handling = 0b111
+            return True
+        return False
+
+    async def set_auth(self, ctx):
+        auth_name = await read(ctx.bizhawk_ctx, [(0x77777, 21, "ROM")])
+        auth_name = base64.b64encode(auth_name[0]).decode()
+        ctx.auth = auth_name
+
+    async def game_watcher(self, ctx: BizHawkClientContext):
+        from . import START_IDS
+        from .items import items
+        from .locations import locations
+
+        (game_loaded_check, level_data, music, auto_scroll_enabled, auto_scroll_levels, current_level, midway_point,
+         bcd_lives) = \
+            await read(ctx.bizhawk_ctx, [(0x0046, 10, "CartRAM"), (0x0848, 42, "CartRAM"), (0x0469, 1, "CartRAM"),
+                                         (rom_addresses["Auto_Scroll_Disable"], 1, "ROM"),
+                                         (rom_addresses["Auto_Scroll_Levels"], 32, "ROM"),
+                                         (0x0269, 1, "CartRAM"),
+                                         (0x02A0, 1, "CartRAM"),
+                                         (0x022C, 1, "CartRAM")])
+
+        current_level = int.from_bytes(current_level)
+        midway_point = int.from_bytes(midway_point)
+        music = int.from_bytes(music)
+        auto_scroll_enabled = int.from_bytes(auto_scroll_enabled)
+        level_data = list(level_data)
+        lives = bcd_lives.hex()
+
+        # there is no music in the title screen demos, this is how we guard against anything in the demos registering.
+        if game_loaded_check != b'\x124Vx\xff\xff\xff\xff\xff\xff' or music == 0:
+            return
+
+        items_received = [list(items.keys())[item.item - START_IDS] for item in ctx.items_received]
+
+        level_progression = {
+            "Space Zone Progression",
+            "Tree Zone Progression",
+            "Macro Zone Progression",
+            "Pumpkin Zone Progression",
+            "Mario Zone Progression",
+            "Turtle Zone Progression",
+        }
+        for level_item in level_progression:
+            for _ in range(items_received.count(level_item + " x2")):
+                items_received += ([level_item] * 2)
+
+        if "Pipe Traversal" in items_received:
+            items_received += ["Pipe Traversal - Left", "Pipe Traversal - Right",
+                               "Pipe Traversal - Up", "Pipe Traversal - Down"]
+
+        locations_checked = []
+        modified_level_data = level_data.copy()
+        for ID, (location, data) in enumerate(locations.items(), START_IDS):
+            if "clear_condition" in data:
+                if items_received.count(data["clear_condition"][0]) >= data["clear_condition"][1]:
+                    modified_level_data[data["ram_index"]] |= (0x08 if data["type"] == "bell"
+                                                               else 0x01 if data["type"] == "secret" else 0x80)
+
+            if data["type"] == "level" and level_data[data["ram_index"]] & 0x40:
+                locations_checked.append(ID)
+            if data["type"] == "secret" and level_data[data["ram_index"]] & 0x02:
+                locations_checked.append(ID)
+            elif data["type"] == "bell" and data["id"] == current_level and midway_point == 0xFF:
+                locations_checked.append(ID)
+
+        if ctx.slot_data:
+            total_stars = ctx.slot_data["stars"]
+        else:
+            total_stars = 5
+
+        invincibility_length = int((832.0 / (total_stars + 1))
+                                   * (items_received.count("Super Star Duration Increase") + 1))
+
+        if "Easy Mode" in items_received:
+            difficulty_mode = 1
+        elif "Normal Mode" in items_received:
+            difficulty_mode = 0
+        elif ctx.slot_data:
+            difficulty_mode = ctx.slot_data["mode"] & 1
+        else:
+            difficulty_mode = 0
+
+        new_lives = int(lives)
+        energy_link_add = None
+        # TODO: temporary check to ensure energy_link key for backwards compatibility
+        if ctx.slot_data and "energy_link" in ctx.slot_data and ctx.slot_data["energy_link"]:
+            if new_lives == 0:
+                if (f"EnergyLink{ctx.team}" in ctx.stored_data
+                        and ctx.stored_data[f"EnergyLink{ctx.team}"]
+                        and ctx.stored_data[f"EnergyLink{ctx.team}"] >= BANK_EXCHANGE_RATE):
+                    new_lives = 1
+                    energy_link_add = -BANK_EXCHANGE_RATE
+            elif new_lives > 1:
+                energy_link_add = BANK_EXCHANGE_RATE * (new_lives - 1)
+                new_lives = 1
+        # convert back to binary-coded-decimal
+        new_lives = int(str(new_lives), 16)
+
+        data_writes = [
+            (rom_addresses["Space_Physics"], [0x7e] if "Space Physics" in items_received else [0xaf], "ROM"),
+            (rom_addresses["Get_Hurt_To_Big_Mario"], [1] if "Mushroom" in items_received else [0], "ROM"),
+            (rom_addresses["Get_Mushroom_A"], [0xea, 0x16, 0xa2] if "Mushroom" in items_received else [0, 0, 0], "ROM"),
+            (rom_addresses["Get_Mushroom_B"], [0xea, 0x16, 0xa2] if "Mushroom" in items_received else [0, 0, 0], "ROM"),
+            (rom_addresses["Get_Mushroom_C"], [00] if "Mushroom" in items_received else [0xd8], "ROM"),
+            (rom_addresses["Get_Carrot_A"], [0xea, 0x16, 0xa2] if "Carrot" in items_received else [0, 0, 0], "ROM"),
+            (rom_addresses["Get_Carrot_B"], [0xea, 0x16, 0xa2] if "Carrot" in items_received else [0, 0, 0], "ROM"),
+            (rom_addresses["Get_Carrot_C"], [00] if "Carrot" in items_received else [0xc8], "ROM"),
+            (rom_addresses["Get_Fire_Flower_A"], [0xea, 0x16, 0xa2] if "Fire Flower" in items_received else [0, 0, 0], "ROM"),
+            (rom_addresses["Get_Fire_Flower_B"], [0xea, 0x16, 0xa2] if "Fire Flower" in items_received else [0, 0, 0], "ROM"),
+            (rom_addresses["Get_Fire_Flower_C"], [00] if "Fire Flower" in items_received else [0xc8], "ROM"),
+            (rom_addresses["Invincibility_Star_A"], [(invincibility_length >> 8) + 1], "ROM"),
+            (rom_addresses["Invincibility_Star_B"], [invincibility_length & 0xFF], "ROM"),
+            (rom_addresses["Enable_Bubble"], [0xcb, 0xd7] if "Hippo Bubble" in items_received else [0, 0], "ROM"),
+            (rom_addresses["Enable_Swim"], [0xcb, 0xcf] if "Swim" in items_received else [0, 0], "ROM"),
+            (rom_addresses["Pipe_Traversal_A"], [16] if "Pipe Traversal - Down" in items_received else [0], "ROM"),
+            (rom_addresses["Pipe_Traversal_B"], [32] if "Pipe Traversal - Up" in items_received else [10], "ROM"),
+            (rom_addresses["Pipe_Traversal_C"], [48] if "Pipe Traversal - Right" in items_received else [0], "ROM"),
+            (rom_addresses["Pipe_Traversal_D"], [64] if "Pipe Traversal - Left" in items_received else [0], "ROM"),
+            (rom_addresses["Pipe_Traversal_SFX_A"], [5] if "Pipe Traversal - Down" in items_received else [0], "ROM"),
+            (rom_addresses["Pipe_Traversal_SFX_B"], [5] if "Pipe Traversal - Up" in items_received else [0], "ROM"),
+            (rom_addresses["Pipe_Traversal_SFX_C"], [5] if "Pipe Traversal - Right" in items_received else [0], "ROM"),
+            (rom_addresses["Pipe_Traversal_SFX_D"], [5] if "Pipe Traversal - Left" in items_received else [0], "ROM"),
+            (0x022c, [new_lives], "CartRAM"),
+            (0x02E4, [difficulty_mode], "CartRAM"),
+            (0x0848, modified_level_data, "CartRAM")
+        ]
+
+        if midway_point == 0xFF and ctx.slot_data and ctx.slot_data["midway_bells"]:
+            # after registering the check for the midway bell, clear the value just for safety.
+            data_writes.append((0x02A0, [0], "CartRAM"))
+
+        if "Auto Scroll" in items_received:
+            if auto_scroll_enabled == 0xaf:  # auto scroll has not yet been enabled
+                data_writes.append((rom_addresses["Auto_Scroll_Disable"], [0x7e], "ROM"))
+                # if the current level is an auto scroll level, turn on auto scrolling now
+                if auto_scroll_levels[current_level] == 1:
+                    data_writes.append((0x02C8, [0x01], "CartRAM"))
+
+        success = await guarded_write(ctx.bizhawk_ctx, data_writes, [(0x0848, level_data, "CartRAM"),
+                                                                     (0x022C, [int.from_bytes(bcd_lives)], "CartRAM")])
+
+        if success and energy_link_add is not None:
+            await ctx.send_msgs([{
+                "cmd": "Set", "key": f"EnergyLink{ctx.team}", "operations":
+                    [{"operation": "add", "value": energy_link_add},
+                     {"operation": "max", "value": 0}],
+            }])
+
+        if not ctx.server or not ctx.server.socket.open or ctx.server.socket.closed:
+            return
+
+        if locations_checked and locations_checked != self.locations_array:
+            self.locations_array = locations_checked
+            await ctx.send_msgs([{"cmd": "LocationChecks", "locations": locations_checked}])
+
+        if music == 0x18:
+            await ctx.send_msgs([{"cmd": "StatusUpdate", "status": ClientStatus.CLIENT_GOAL}])
+            ctx.finished_game = True
+
+    def on_package(self, ctx: BizHawkClientContext, cmd: str, args: dict):
+        super().on_package(ctx, cmd, args)
+        if cmd == 'Connected':
+            ctx.set_notify(f"EnergyLink{ctx.team}")
+            if ctx.slot_data and "energy_link" in ctx.slot_data and ctx.slot_data["energy_link"] and ctx.ui:
+                ctx.ui.enable_energy_link()
+                ctx.ui.energy_link_label.text = "Lives: Standby"
+        elif cmd == "SetReply" and args["key"].startswith("EnergyLink"):
+            if ctx.ui:
+                ctx.ui.energy_link_label.text = f"Lives: {int(args['value'] / BANK_EXCHANGE_RATE)}"
+        elif cmd == "Retrieved":
+            if f"EnergyLink{ctx.team}" in args["keys"] and args['keys'][f'EnergyLink{ctx.team}'] and ctx.ui:
+                ctx.ui.energy_link_label.text = f"Lives: {int(args['keys'][f'EnergyLink{ctx.team}'] / BANK_EXCHANGE_RATE)}"

worlds/marioland2/docs/en_Super Mario Land 2.md

@@ -0,0 +1,58 @@
+# Super Mario Land 2: 6 Golden Coins
+
+## 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 items and locations get shuffled?
+
+Completing a level's exits results in a location check instead of automatically bringing you to the next level.
+Where there are secret exits, the secret exit will be a separate location check. There is one exception, Hippo Zone,
+that does not have a separate check for its secret exit. The Hippo Zone secret exit will still bring you to the Space
+Zone.
+
+Unlocking paths to new levels requires finding or receiving Zone Progression items. For example, receiving the first
+"Turtle Zone Progression" will unlock the path from Turtle Zone 1 to Turtle Zone 2. Paths to secret levels are separate
+items, so Turtle Zone Secret will open the path from Turtle Zone 2 to the Turtle Zone Secret Course.
+
+Mario Zone, Pumpkin Zone, Tree Zone, and Macro Zone each have one "Zone Progression x2" item that opens two paths at
+once.
+
+The path from Tree Zone 2 to the branch to Tree Zone 3 and 4 is one unlock, so both levels will open at this point.
+
+Besides the zone progression unlocks, the following items are always shuffled:
+- Mushroom: required to become Big Mario. If you are Fire or Bunny Mario and take damage, and have not obtained the
+Mushroom, you will drop straight down to Small Mario.
+- Fire Flower: required to become Fire Mario.
+- Carrot: required to become Bunny Mario.
+- Swim: Mario will fall through water as though it is air until this is obtained.
+- Hippo Bubble: required to use the bubbles in Hippo Zone to fly.
+- Space Physics: the Space Zone levels will have normal gravity until this is obtained.
+- Super Star Duration Increase: you begin with a drastically lowered invincibility star duration, and these items will
+increase it. This is the main filler item and the number of them appearing in the item pool depends on your settings.
+
+Additionally, the following items can be shuffled depending on your YAML settings:
+- The 6 Golden Coins: note that the game will still show you the coin being sent to the castle when defeating a boss
+regardless of whether the coin is actually obtained in that location.
+- Midway Bells: ringing bells results in a location check, and the midway check points are shuffled as items.
+Note that you may have to backtrack from the midway point to reach some secret exits!
+- Normal Mode/Easy Mode: you can start the game in Normal Mode with an Easy Mode "upgrade" in the item pool, or start in
+Easy Mode with a Normal Mode "trap" item, swapping the difficulty.
+- Auto Scroll: auto-scrolling levels can be set to not auto scroll until this trap item is received.
+- Pipe Traversal: required to enter pipes. Can also be split into 4 items, each enabling pipe entry from a different
+direction.
+
+
+## When the player receives an item, what happens?
+
+There is no in-game indication that an item has been received. You will need to watch the client to be sure you're aware
+of the items you've received.
+
+## Special Thanks to:
+
+- [froggestspirit](https://github.com/froggestspirit) for his Super Mario Land 2 disassembly. While very incomplete, it
+had enough memory values mapped out to make my work significantly easier.
+- [slashinfty](https://github.com/slashinfty), the author of the
+[Super Mario Land 2 Randomizer](https://sml2r.download/) for permitting me to port features such as Randomize Enemies
+and Randomize Platforms directly from it.

worlds/marioland2/docs/setup_en.md

@@ -0,0 +1,75 @@
+# Setup Guide for Super Mario Land 2: 6 Golden Coins
+
+## 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.9.1 is recommended.
+  - 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)
+- A Super Mario Land 2: 6 Golden Coins version 1.0 ROM file. The Archipelago community cannot provide this.
+
+## Configuring BizHawk
+
+Once BizHawk has been installed, open EmuHawk and change the following settings:
+
+- 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" box. This will prevent disconnecting from the client while
+EmuHawk is running in the background.
+
+It is strongly recommended to associate GB rom extensions (\*.gb) to the EmuHawk we've just installed.
+To do so, we simply have to search any Gameboy 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 generate a yaml or download a template by visiting the [Super Mario Land 2 Player Settings Page](/games/Super%20Mario%20Land%202/player-settings)
+
+## Joining a MultiWorld Game
+
+### Generating and Patching a Game
+
+1. Create your settings file (YAML).
+2. Follow the general Archipelago instructions for [generating a game](../../Archipelago/setup/en#generating-a-game).
+This will generate an output file for you. Your patch file will have a `.apsml2` file extension.
+3. Open `ArchipelagoLauncher.exe`
+4. Select "Open Patch" on the left side and select your patch file.
+5. If this is your first time patching, you will be prompted to locate your vanilla ROM.
+6. A patched `.gb` file will be created in the same place as the patch file.
+7. On your first time opening a patch with BizHawk Client, you will also be asked to locate `EmuHawk.exe` in your
+BizHawk install.
+
+You must connect Super Mario Land 2 to a server, even for a single player game, or progress cannot be made.
+
+### Connect to the Multiserver
+
+By default, opening a patch file will do steps 1-5 below for you automatically. Even so, keep them in your memory just
+in case you have to close and reopen a window mid-game for some reason.
+
+1. Super Mario Land 2 uses Archipelago's BizHawk Client. If the client isn't still open from when you patched your
+game, you can re-open it from the launcher.
+2. Ensure EmuHawk is running the patched ROM.
+3. In EmuHawk, go to `Tools > Lua Console`. This window must stay open while playing.
+4. In the Lua Console window, go to `Script > Open Script…`.
+5. Navigate to your Archipelago install folder and open `data/lua/connector_bizhawk_generic.lua`.
+6. The emulator may freeze every few seconds until it manages to connect to the client. This is expected. The BizHawk
+Client window should indicate that it connected and recognized Super Mario Land 2.
+7. To connect the client to the server, enter your room's address and port (e.g. `archipelago.gg:38281`) into the
+top text field of the client and click Connect.
+
+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]`)