Amalgam PC home Arcturus Linux home Windows Applications ArcBundle Format Scripting APIs

ArcBundle format specification


ArcBundle overview

ArcBundles are a method of storing programs in a generic, easily interpretable, archivable, recompressible format that can supply all the necessary functionality for every computer type concievable. This specification is still being worked on, and new features are being added to better accomodate a diverse collection of different computing devices. Many of the ArcBundle features are intended for only one system type, and do not make sense outside of that platform. These features are considered extensions to the base standard, and do not function on all system types. Please make note of which features are supported for your system type when bundling software to prevent unexpected behavior.


ArcBundle Functionality

ArcBundles are automatically run with emu-run when a user double-clicks on one. This wrapper takes care of unpacking and setting up the program contained. Some of this setup may require additional content to be downloaded from the internet. To enable users to run this software without an internet connection, the emu-install program is also provided. This can be selected by right-clicking on an ArcBundle and selecting install. This second script does all of the tasks involved in setting up a bundle, but doesn't actually run it, allowing it to be used later offline.

ArcBundle Format

At its most basic, an ArcBundle is simply an archive file containing everything a program needs to run. Nearly every archive format is supported, including but not limited to ZIP, RAR, and 7z. 7zip archives are preferred, as these archives have fairly good compression, are easy to create and unpack with many different programs, and store a file table that can be read without parsing the entire archive file the way a TAR archive does. This makes them much easier to work with over a network or internet connection. What information is stored in the archive is dependent on the original host system:

Other similar formats exist, and some overlap the functionality here. A few are outlined below, with info on support through these wrappers.


Mods

Mods are stored as regular folders in two locations:

This allows automatic mod management and allows the user to sync mods between computers with saved data, which is often necessary to make game saves work when playing with mods. The .arcturus folder is intended for system-wide mods, which are generally core mod support or managers, and the [HOME]... mod folder is intended to store the actual mods themselves, which allows each user of a system to run their own mods without altering the program for other users of a system. The contents of these folders will be laid over the top of the program folder, and the program will only see the final result. User mod folders override the system mod folder, so if a file exists in both only the user mod version will be used. Do be aware that the host filesystem - UnionFS - cannot tell whether a program wrote to a file if it is opened in write mode. This can cause some programs to copy some or all of the mod files to the savedata folder, and can cause some slowdown the first time each file is accessed in this way. This might cause undesired operation if these files are later updated, so adding a script-fork-rmrec to remove these files might be needed. Be careful with that command, though, as it will COMPLETELY DESTROY everything you point it to, automatically gaining elevated permissions if needed.

Managed Mods

Managed mods are just like regular mods, except each mod's files and folders are stored in an arcmod file, which is a regular arcbundle archive that has a different file extension to prevent programs that search subdirectories from erroneously detecting these files as unique programs themselves. Multiple mod bundles can be stored in the folder, and the locations checked are as follows:

Managed mods are unpacked in alphabetical order whenever one changes, and are meant to handle mods where some file collisions may occur. If mod load order matters because of these collisions, you should name these mods so that an alphabetical sort will place them in the correct locations. For example:

001-sample1.arcmod

002-sample2.arcmod

This will ensure that files will be overwritten in the proper order. If script-mod-unpack-cleanup-override or script-coremod-unpack-cleanup-override are declared, these will be called after each mod is unpacked to remove common fluff that is unnecessary. This will not automatically handle configuring a program to load these mods in this order, but script-post-mod-install will be called if defined, and script-output-managed-mods will dump the list in the same order they are unpacked. This can be enough for some uses, but script-output-managed-mod-files may be necessary for others. Note that the latter function outputs every file in every mod, so you will likely need to use grep to filter this list to make the mod load config for your program. This function can be called multiple times, and it reads from cached data, so it doesn't need to read every byte of every file every time it is called. This still does not list which mod package each file comes from, as the destination program isn't going to see that data, so it is assumed to not be useful. If that assumption is incorrect, contact us to have additional functions added for your usecase.

To allow the managed mod tools to reuse the pre-packaged mod files that some modders distribute as an archive file, the script-mod-dir command exists. This command will tell the managed mod system to unpack all mod bundles to whatever folder path is specified, relative to the main program folder. "script-mod-dir Mods" will force all mods to unpack to the "Mods" folder inside of the program's main path, and is often enough to allow mods to automatically work when downloaded, renamed to end in .arcmod, and stacked into any of the managed mod folders. Please note that the managed mod tools will attempt to extract any file stored in these folders, so DO NOT put random data files in these folders. You have been warned. Subdirectories of these folders will also be scanned, all in alphanumeric order. You can use folders to sort mods for unpacking priority, but NEVER put anything but mods you want to use in these folders. This does not make subdirectories named after the mod file name, so some games will still need mod package reworking. A future command to correct this is planned.

Packages ending in .arccoremod instead of .arcmod are unpacked to the root game directory instead of the mod folder. These are generally mod loaders, libraries, or game updates. script-coremod-unpack-cleanup-override will get called once for each coremod unpacked, to allow for cleanup of common cruft.

System-specific extensions

Primer: things to know

The automatic scanners generally do the right thing, and most fixes recommended on WineHQ or other sites aren't needed here. If in doubt, try the program first before attempting to patch it. The following patches are automatically detected in most cases:

Please note that there are a few stubborn libraries that just don't work without Winetricks installing the official version AND can't be automatically detected because the way they are called leaves no obvious text strings in the program data. The currently known troublesome libraries are: At this time, there is no known way to autodetect these libraries, and Wine does not yet fully implement their functionality to the extent required for full compatibility. In order to make programs that use these libraries function correctly, we unfortunately need to call windows-winetricks-install [winetricks package name] in the arcturus-config script. It is unlikely that Wine will provide full support for many of these libraries, so this shouldn't cause serious problems for future compatibility.

prgdir

Supported for: Windows

Some programs have hard-coded location information in their files or registry entries, and our write-redirection really messes with them. To prevent this issue from occurring, always install the program to C:\prgdir. Before running the program, the wrappers will set this to the correct location of the program, allowing us to still use write redirection through randomly-generated folder names without murdering the program in the process.

arcturus-config

Supported for: Windows and Linux

Programs for all computer platforms support a Bash script named arcturus-config in the root of the archive, next to the program itself. For mod or expansion packages scripts stored in a folder named arcturus-config can be used instead, allowing further tweaks to the configuration on a per-mod or per-expansion basis. These scripts are automatically run before the program, and can make folders, apply special patches a program might need that are not typical, or provide additional functionality. This script is generally not required, and as it is simply run as a Bash script, all Bash functionality is available. Some additional commands to control the wrapper are also available for use:


install_data.reg

Supported for: Windows

Windows programs sometimes require registry settings to run correctly. Any necessary registry settings should be exported via regedit to a file named install_data.reg stored in the root of the ArcBundle. This regfile will be automatically imported before the program is run. If you need multiple hives, simply copy the contents of extra regfiles to the first one without the [REGEDIT4] line. This will make a single regfile with all of the necessary changes. For mods or expansions, simply save a reg file in a FOLDER named install_data, and we'll automatically enter each file one at a time before running the main program.


wine_windir - wine_drive_c - wine_program_files - wine_program_files_32

Supported for: Windows

Windows programs also sometimes need to reference files stored in other directories. As these folders are managed by Wine, we need to add some magic to add these files. Simply put them in the correct folder in the main program directory, and Arcturus will take care of copying these files to the correct location. Subdirectories are supported, but care should be taken to avoid adding files provided by Wine or Arcturus to ensure everything works correctly. In other words, if you're not sure if a file belongs here, don't include it.

The folder names and uses are:


wine_drives

Supported for: Windows

Windows programs sometimes need a disc in an optical drive to run. This functionality isn't always well-supported through Wine, so a pair of workarounds exists. This is a folder containing subfolders named drive_d (or drive_e, etc.) that get automatically mounted as virtual optical drives before the program is run. The drive letter is determined by the name of the folder, so drive_d will always be D:, drive_e will always be E:, and so on. Drive letters up to Z can be used, but C and Z are reserved and should never be used for this purpose.


drive_d.iso

Supported for: Windows

Sometimes the folder approach above just doesn't cut it. For programs that just don't like the folder method, an ISO image can be used instead. Put it inside the wine_drives folder as before, then name it drive_d.iso for D:, drive_e.iso for E:. Drive letters up to Z can be used, but C and Z are reserved and should never be used for this purpose.
Yes, we know we said ISO images were limited in scope above, but this format is hard-coded into Wine, so if a program makes use of incompatible data (generally as one of those oh-so-fun copy-protection schemes), the program or its settings may need to be patched to not require a disk at all. As this may be illegal in your country or region (read: if your lawmakers don't understand computers), there may just not be another way. We're looking into integrating some more sophisticated image mounting techniques, but as Linux and Wine generally just fold those down to the data that could be expressed in an ISO anyway, this may not prove to be better.