FiendsOfTheElements / FF1Randomizer

FF1 Randomizer This is a randomizer for Final Fantasy 1 for the NES. It currently operates on the US version of the ROM only. A randomizer takes certain elements of a game and randomize them, creating a whole new gameplay experience. If you just want to play, it is deployed at https://finalfantasyrandomizer.com Project Structure The general project structure is as follows: • UI: FF1Blazorizer • Actual logic: FF1Lib • Desktop Application (Obsolete): FF1Randomizer • Command line FFR: FF1R • Shared Desktop and Command line stuff: FFR.Common • deployment scripts: .circleci Architecture The randomizer is written in C#. The user interface is written using Blazor. Blazor is a web framework that includes the ability to run .NET applications directly in the browser. This means that the randomizer is able to run entirely on the user's computer and is cross-platform without users having to explicitly download or install anything. Different randomizer versions are handled as instanced deploys. The version is embedded in the URL as https://4-5-1.finalfantasyrandomizer.com, https://4-5-2.finalfantasyrandomizer.com, etc and the finalfantasyrandomizer.com start page is just a redirect to the latest version. Most of the code that actually changes the ROM can be found in FF1Lib. The entry point for randomization is FF1Rom.Randomize(). It is initalized with the starting ROM and then goes through and makes all the changes that the user selected. You should read data from the ROM using FF1Rom.Get() or FF1Rom.GetFromBank() and apply changes using FF1Rom.Put() or FF1Rom.PutInBank(). Some data is loaded into tables which are written back at the end. In these cases, reading the data and writing it back will produce incorrect results. Check FF1Rom.LoadSharedDataTables(). Offsets used by Get() and Put() do not include the 16 byte iNES header from the .nes file. If you are getting ROM offsets from somewhere else (like another ROM hack) they might be .nes file offsets which will be 16 bytes greater than the correct ROM offset. The randomizer changes the mapper from MMC1 to MMC3 in order to bump the ROM size from 256k to 512k and have more space for hacks. It also moves some code out of their original locations into the newly available banks. When creating patches, be aware that some functions may have moved. The web user interface can be found in FF1Blazor. It calls FF1Rom.Randomize() in FileTab.razor. When adding a new flag, you need to add it to FF1Lib.Flags and FF1FLib.FlagsViewModel. The latter class wraps the Flags in order to raise events when a flag is changed (used to trigger a re-render by the UI). The FF1Rom.Randomize() method is an asynchronous method. Because randomization can take a while, it periodically returns control to the caller using "await" to give the browser's javascript event loop a chance to process input, re-render, etc. This is necessary because the .NET virtual machine that executes the randomizer is written in webassembly and runs in the same thread as the page's javascript. The randomizer has been touched by a number of people with varying style, programming skill, goals, and at different points of evolution of abstractions in the code base. As a result, different features manipulate the ROM in many different ways. When in doubt, prefer to use functions and classes that abstract interaction with the ROM instead of just blindly changing bytes, it will be less likely your feature has unintended interactions with other features. Setting up a Development Environment • Download and install Visual Studio • In the Visual Studio Installer, select the following optional pieces: ASP.NET and web development .NET desktop development • Clone the randomizer (git specific information below) • All done! Developing on Linux • Download and install the .NET SDK • • ROM hacking Using ca65 to assemble code For example, if you need to assemble and get a hex string (the listing is optional but incredibly helpful): Hot-patch in the fceux debugger for testing • Run the game in fceux, find what you care about in the debugger • Click "ROM offsets" to ensure it is on, • Open the Hex Editor, then view -> Rom file • Ctrl + a to goto an address, input the rom offset • Input the assembled hex • It will update live Git workflow The randomizer is hosted on github and therefore some level of git knowledge is required in order to contribute. In order to help get anyone ready to contribute, this will assume no prior git knowledge. Please skip past any steps you have already done, or this entire section if you are already familiar with git and able to rebase, merge, deal with multiple repos, bisect, and handle PRs on github. Basic Description Git A version control system. This will control a folder or directory for you, managing the files inside it so you can swap between versions of those files. Git Terms • commit: A discrete piece of history in the version control system. • branch: A distinct history of the files in the git directory. This can have a history that shares a common ancestor with another branch (the usual case) or be fully separate. Usually features/bugfixes start with a new branch off the main branch. • repo, repository, or remote: A remote server that facilitates distributed development through being a synchronized source of truth for the files in the git directory. There can be multiple repos. • rebase or merge: Methods of taking changes that are in a repo and combining them with your local work. • pull and push: Transferring files from the repo to your local stuff or the other way around. • clone: The action of setting up a local git directory that is a clone of a specific repo. • checkout: Swap to a different branch or commit. • use to see what the current situation in your local git directory is. Github A company that provides git hosting services. Github Terms • Fork: A separate repo of a project on github, copied at a specific point in its history. You will likely have a f…