monorail
/
Archipelago
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: rewrite patch section (#336) 

this gets rid of a lot of information that is not required
and somewhat adds best practice to it
This commit is contained in:
black-sliver 2022-03-24 00:47:27 +01:00 committed by GitHub
parent 8e59761b03
commit a6b22d1f41
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 30 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
docs/adding games.md
View File

@ -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