From a6b22d1f41c35460ee1accc055e85f7357c7a9d7 Mon Sep 17 00:00:00 2001 From: black-sliver <59490463+black-sliver@users.noreply.github.com> Date: Thu, 24 Mar 2022 00:47:27 +0100 Subject: [PATCH] Doc: rewrite patch section (#336) this gets rid of a lot of information that is not required and somewhat adds best practice to it --- docs/adding games.md | 69 +++++++++++++++++++------------------------- 1 file changed, 30 insertions(+), 39 deletions(-) diff --git a/docs/adding games.md b/docs/adding games.md index 0a76cb66..79b874a1 100644 --- a/docs/adding games.md +++ b/docs/adding games.md @@ -190,53 +190,44 @@ This is a good way to get any project you're working on sued out from under you. The right way to distribute modified versions of a game's binaries, assuming that the licensing terms do not allow you to copy them wholesale, is as patches. -There are many patch formats, which I'll cover in brief. The common theme is that you can’t distribute anything that wasn't -made by you. Patches are files that describe how your modified file differs from the original one, thus avoiding the -issue of distributing someone else’s original work. +There are many patch formats, which I'll cover in brief. The common theme is that you can’t distribute anything that +wasn't made by you. Patches are files that describe how your modified file differs from the original one, thus avoiding +the issue of distributing someone else’s original work. Users who have a copy of the game just need to apply the patch, and those who don’t are unable to play. - -### IPS Patches -This is an extremely simple, early patch format, but is limited to games of about 16 Megabytes in size or less. -You will often find IPS patches being used to distribute mods for old video game ROMs. -IPS patches are a delta patch format, which means they act only as a simple list of alterations that need to be made to -an original file in order to produce a new one. -Archipelago may use pre-made IPS patches to apply specific changes to a game, but will not create IPS patches as a means -of distributing game modifications. Although IPS patches can be applied quickly, creating them is quite slow, so using -them for distributing randomized games is not current practice. +### Patches -However, due to the format's simplicity, even patch files of this type can unintentionally include copyrighted data. -This is because IPS patches don't have a good way to shift existing data in a file, and thus if data has to be moved -forward x number of bytes, which might be necessary for data insertion, the patch will simply include a copy of the -shifted bytes after the inserted ones. -Increasing and decreasing file size is also not a universally supported operation, due to the patch format's age. - -### BPS Patches -BPS is the younger cousin of the IPS patch. +#### IPS +IPS patches are a simple list of chunks to replace in the original to generate the output. It is not possible to encode +moving of a chunk, so they may inadvertently contain copyrighted material and should be avoided unless you know it's +fine. -More flexible and theoretically future-proofed for any file size, BPS patches are based on the idea of linear patching. -Unlike IPS patches, which use a system called delta patching, linear patches act as a series of steps for creating a -modified file from scratch through a combination of original data and patch data, which is appended onto the end of the -modified game file as the patch progresses. +#### UPS, BPS, VCDIFF (xdelta), bsdiff +Other patch formats generate the difference between two streams (delta patches) with varying complexity. This way it is +possible to insert bytes or move chunks without including any original data. Bsdiff is highly optimized and includes +compression, so this format is used by APBP. + +Only a bsdiff module is integrated into AP. If the final patch requires or is based on any other patch, convert them to +bsdiff or APBP before adding it to the AP source code as "basepatch.bsdiff4" or "basepatch.apbp". + +#### APBP Archipelago Binary Patch +Starting with version 4 of the APBP format, this is a ZIP file containing metadata in `archipelago.json` and additional +files required by the game / patching process. For ROM-based games the ZIP will include a `delta.bsdiff4` which is the +bsdiff between the original and the randomized ROM. + +To make using APBP easy, they can be generated by inheriting from `Patch.APDeltaPatch`. -This means that some operations, like inserting data into the middle of a file instead of simply overwriting it, -are much easier to do. -However, like IPS, it isn't a format well suited to randomizers, due to the asymmetric costs of creating and applying -BPS patches. - -### Xdelta Patches -Xdelta is the true successor to IPS, featuring better optimization and verification, and manages to transcend many of -the limitations of IPS. However, Xdelta patches are particularly expensive to create. - -### bsdiff -bsdiff is the current format adopted by Archipelago for creating and distributing patches. -It is much faster to create patches of this variety, which is why it sees use in this application. - ### Mod files Games which support modding will usually just let you drag and drop the mod’s files into a folder somewhere. -Mod files come in many forms, but the rules about not distributing other people's content remain the same. - +Mod files come in many forms, but the rules about not distributing other people's content remain the same. +They can either be generic and modify the game using a seed or `slot_data` from the AP websocket, or they can be +generated per seed. + +If the mod is generated by AP and is installed from a ZIP file, it may be possible to include APBP metadata for easy +integration into the Webhost by inheriting from `Patch.APContainer`. + + ## Archipelago Integration Integrating a randomizer into Archipelago involves a few steps. There are several things that may need to be done, but the most important is to create an implementation of the