dashrando / dash-randomizer

Super Metroid DASH Randomizer

DASH Randomizer

DASH is a Super Metroid randomizer aimed at competitive play.

This is a monorepo which consists of all the DASH projects, which are located in the apps and packages folders.

• web: the website for dashrando.net
• headless: a standalone Node.js version which can be used to generate seeds outside of the website (such as bots).
• core: the logic for seeds for each mode.

Local Development

Dependencies

First install the dependencies for the monorepo. Node.js v18 is required.

npm install

This monorepo is powered by Turborepo. You will need to follow their installation instructions and ensure it is installed.

Running Apps

To run all apps in parallel, you will need to run the dev command.

npm run dev

If you only want to run a single app, you will need to go to that folder and run the dev command there. For example, to run the website, you would do something similar to the following.

cd apps/web
npm run dev

dash-randomizer's Issues

Incorrect spoiler info for majors at shifted boss locations

We are not writing spoiler information for major items that are at shifted boss locations. This is because of how we index into the list of item locations in the rom. Basically, we need to just use the vanilla address of the item location for looking up the name for now. We can do a better version of this later.

Odd values shown on logic page

Seeing some weird values on the logic page:

Something about the parser that generates the static pages.

Refactor scripts to use modules

We should be using modern javascript modules to improve readability and maintainability.

Simplify signature generation code

We have code on the website that generates the same signature that shows up on the file select screen. We initially implemented this by grabbing values out of the seed patch that we generate, and we are still doing it that way. encodeBytes etc. We don't have to do all of that though. We should just be able to call U16toBytes a few times, grab the output, and set the values. Pretty low priority.

About Page

We need to have a page about DASH at /info/about. This should describe the goals of DASH along with our motivations and design philosophy.

Dieter Rams Ten Principles of Good Design is a reference.
https://www.vitsoe.com/eu/about/good-design

Support item location obfuscation

We need to make it harder to look at the items that are placed are each location. Previously we relied on total's RandoCrypt tool, but our current template rom is no longer compatible with it. That's ok because it is kind of a black box (intentionally) and always made me nervous to use it on DASH seeds.

I think the meta PLMs that we support (jump, skip, etc.) could be used or extended to allow us to create more complicated logic for getting the PLM for each item location. That should be good enough for a first step and might be sufficient long term vs implementing actual encryption.

Show feedback on longer seed generation

If a seed takes over 100ms to generate, we should provide visual feedback that the seed is being generated and is working. We should also provide a timeout if seed generation fails.

Never reference vertices by name

We currently have several places where we assume certain values or formats for vertex names. This was intended to be temporary until we came up with a better way. It's time to fix that.

More than likely, the best solution is to improve the type value associated with each node. For example, we might want an "exit" type for boss exits since we look for the Exit_ prefix several times. Another good type might be "door" as we currently look for Door_ in several places. Honestly, doing those two might be enough to get us to good.

Update Recall changes on Homepage

Update the homepage to reflect all of the new changes in Recall. This should also link to the video collection vs having multiple embeds.

Info Page design

The /info page needs to have a design to show all of the info pages.

Samus Sprite ROM Re-Architecture, Frontend Sprite Tool, and Proposed dash-bin-ext

Tasks

Moving forward on Samus sprites, we have two tasks ahead.

1. Build in "native" ROM support for custom sprites in the SpriteSomething png format. This should be part of the base ROM build and include the vanilla Samus sprite.

SpriteSomething fundamentally changes how sprites are handled and drawn in some respects. It uses the same VRAM space as vanilla but with (mostly)16-pixel height chunks as a sort of viewport into various poses with minimal flipping and mirroring (this relaxes symmetry requirements that sprite artists would otherwise be very constrained by.) At a high level, the Samus pose/animation code is changed to support this and some extra space for data is claimed.

We need to write our own, equivalent implementation using theirs as a reference (https://github.com/Artheau/SpriteSomething/blob/master/source/snes/metroid3/samus/rom_inject.py). Additionally, we should build this implementation directly into the base build such that the vanilla player sprite works exactly the same as a custom sprite. This will make any debugging/testing easier and in my opinion is also a matter of racing integrity. In practice there is probably little to no difference in timing between a vanilla and custom sprite, but all ROMs should be executing the same code here all things being equal. There are various ways to approach this, more on that below.

One question that needs to be resolved here as well is whether or not to support the original screw-without-space jump animations. We could simply not implement them even though they're in the png. My vote would be to not include this in our implementation.

2. Build a frontend tool that takes a standard SpriteSomething png layout and produces the binary data to be patched.

With #1, we've laid out a specification for this and should be able to more or less do a straightforward binary transformation. We should also use SpriteSomething as a reference here, and potentially use their json data descriptions keeping in mind that they are licensed under CC BY-SA 4.0.

We also have to decide how to implement the necessary tools here. The patcher and any potential tools for the base ROM build should be designed as a library exposing some simple input-output interface. The most straightforward option would be to implement them in Typescript like the rest of the project. I would propose writing the core tools in Rust with webassembly bindings. It's an ideal candidate for the fast binary transformations we want, and can additionally be compiled as its own Rust library or have bindings for other languages written. There are, of course, complexity and maintenance tradeoffs here as well.

Binary Extensions Repo/Side-Project

When we reach this point, we should probably make a separate issue and discuss this more thoroughly. But I don't want to put the cart before the horse here. I was thinking we could maintain separate repo for binary tools/extensions/bindings. Something like dash-bin-ext. We could more broadly imagine writing tools or drop-in functions that expose a TS API in a compiled language like Rust. For example, we could compile a tool that converts the vanilla player sprite to the new format and place it in the ROM repo's /bin directory to be used alongside the assembler as part of the build. Or we could, theoretically, write a level composer (as a drop-in for the current "hot" patching) or graph solver that takes some input from the TS application and outputs either some native data to be used by the app or binary data to be patched.

Easy Mode

Although we don't want too many knobs for users, it is clear that some of the logic in DASH is not accessible to newer runners. In particular, things related to suits. We'd like to add an Option that restricts seeds from requiring hell runs and suitless maridia.

Easy Mode would be curated by the team and additional restrictions could be added later based on feedback. The name Easy Mode is probably not the best. Since it's an Option, maybe the field is "Skill Level" or something like that. We'll need new documentation for this as well. In my mind, we don't really worry about balancing Easy Mode for racing in the way that we do Default Mode. That should be explained on the site.

Approaches

As for how we implement the mode at the graph level, I see two potential options:

1. Update loadout.ts and the various edge files to expressly limit things
2. Generate seeds and verify that they don't require hell runs or suitless maridia
3. Override the entry edges (and a few others) for maridia and norfair to require gravity/PV and varia/HS ⭐

Approach 2 was my preferred solution at first because it fits more into how we currently generate seeds in DASH. It has the big benefit of not having to overcomplicate the graph/loadout logic. It might be too hard though because properly detecting whether or not a seed required suitless for progression is not trivial.

We already have a simple way to implement hell run restrictions for Approach 1 because of the HellRunTanks property. Perhaps we could do a SuitlessHJB or simple add an AllowSuitless flag.

Approach 3 follows the same design we use for implementing changes for Recall and Area on top of the standard graph. Since each area has an edge between the door and the first room, we can put a restriction there to limit things. We already do this for LN where we have HasVaria as a requirement here:

  Door_RidleyMouth: {
    Ruins: () => HasVaria && (HasGravity || HasHiJump),
  },

  Door_Muskateers: {
    Muskateers: () => HasVaria,
  },

The current plan is to go with Approach 3

Info Page for DASH: Recall

The current homepage has info about DASH: Recall that needs to be moved to its own standalone page in the redesign.

Fix API route for new options

API Route for Seed Generation is currently broken after refactoring seed generation. This needs to be fixed before it can be released.

Support all options on seed page

The new seed page added by kupppo is great, but we need to support all options (currently only fanfare toggle). Since we are writing 96-bits of flags into the rom with info like mode, item placement logic, and the fanfare flag, we should look at allowing the seed page to read a base64 encoded version of that value and using it.

It also makes sense to change the param names again to "num", "preset", and "flags". We would ignore preset if "flags" are specified and probably print a warning in the console. For now, we can show an error on the page if "num" is missing or if both "preset" and "flags" are missing.

Remove header in vanilla drag + drop

Drag + drop doesn't deheader the ROM and it should.

Need an info page describe all game mods

On the old site, we had https://www.dashrando.net/updates which gave a full list of all game mods (soft-lock preventions, etc.) but didn't actually cover Recall specific changes. Those were on the front site. Now that we let runners pick more settings, we probably are good with our Settings documentation, but we still need a list of the standard game mods somewhere.

We probably need to discuss map changes more in the Settings page for Map Layouts. We are gonna be adding back the DASH Classic Map Layout soon too.

Setup Sentry for web

We should use Sentry to track bugs in both canary and production.

Fix Headless for new options

Headless is currently broken after refactoring seed generation. This needs to be fixed before it can be released.

Incorrect Mode shown on Generate page when going back from Seed page

If you roll a seed on the Generate page, and then click on the associated Seed page link, everything works nice and the Seed page pops up showing all correct settings/options. If you then go back in the browser, the Generate page remembers all settings/options, but the Mode at the top always defaults back to the first entry.

For example, roll a DASH: Recall seed, click the Seed page, go back, you will see that the Mode shows SGL23 but the settings below are still Recall settings.

Add back Classic options once ROM changes are ready

We are gonna write the addresses we need to interfaces.ts as part of the rom build process. Once we have the in place, we can update the site to support generating Classic seeds again. This should include updating the settings page when necessary.

Allow generation of seeds with random settings

We would like to add a choice for each setting that allows the value for that setting to be chosen randomly. This would allow for us to build a preset which could produce a random seed with certain restrictions. Maybe I want a seed that picks a random Item Split (Major/Minor, Full, Chozo), but I want to fix everything else. I would simply pick "Random" as the choice for Item Split, press Generate, and it would give me a seed.

Would probably be nice to have "Random" as an option for the Modes/Presets at the top too.

Ideally, we'll put "Random" as a choice at the bottom of the values for each setting after a separator.

Also, the word "Random" may not be the best choice. Maybe something like "Pick for me" instead. We don't want to overuse the word "Random" because then it will lose it's meaning.

---

UPDATE May 2024 - This has been partially implemented with the mystery preset. That one uses more of a hardcoded approach and works exclusively via the API (aka via bots). We should look at building custom Mystery settings and allow those seeds to be created from the /generate page.

Require HJB or Gravity to enter Mama Turtle

We currently only require HJB or Gravity to exit Mama Turtle. This means those items could be there and could be your only way of getting back out. We saw this at SGL, and the feedback was that we should not let that happen. We should be able to add HJB/Gravity to the logic to get to Mama Turtle. I believe the edge is "From Supers (Crab) to Missiles (Mama Turtle)"

Remove Recall Area from Logic page

We currently have four options on the logic page: Standard, Standard Area, Recall, and Recall Area. At a minimum, we need to remove Recall Area because that isn't actually a thing. Ideally, we might change it to: Standard Map, Area Randomization, and Recall. Basically, we want the choices to mirror the Map Layout options on the Generate page.

Add node name to Location class

We currently have a separate step where we call mapLocation to match up node names with Location names. Ideally these would be the same value. We might adjust the data files eventually, but until then we should add a field to the Location class for the node name. Then we can remove the mapLocation function. This will likely speed up seed generation a bit because profiling shows that we spend a lot of time in the mapLocation function. Low priority.

Add route to GET available presets

For bot development, it would be good if we exposed a route where someone could GET the currently available presets. The current seed route should also honor this list of presets.

Incorporate Rumbleminze's tracker into the website

include it in the dash site proper