RFC: Enhancement of DCS Dropzone Mod Manager with `install.md` File Integration

[JonathanTurnock]

1. Introduction

Background

DCS Dropzone has evolved to use Markdown files with YAML front matter for mod properties and release information. This approach has significantly improved flexibility and clarity. However, there's still potential for further enhancement, particularly in the installation process of mods.

Objective

This RFC proposes the integration of an install.md file into the DCS Dropzone Mod Manager. The install.md file will contain instructions for creating symlinks to target directories, enhancing the mod installation process. Additionally, it will handle hash-routed files, streamlining the process of sourcing mod files from external URLs.

2. Proposed Changes

New File: install.md

• Purpose: install.md will serve as an instruction set for creating symlinks from the mod package to the target directories in the user's file system.
• Contents: It will contain YAML front matter for listing files/folders and their target directories. Additionally, it will support hash-routed URLs for sourcing files.

Structure of install.md

• The file will list each file/folder in the mod package that needs to be symlinked.
• For each item, the source URL (possibly hash-routed) and the target directory on the filesystem will be specified.

Example install.md

---
- source: "http://xyz.com/simple-script.lua"
  target: "/path/to/target/directory/simple-script.lua"

- source: "http://xyz.com/my-mod.zip/#/my-folder/script.lua"
  target: "/path/to/target/directory/script.lua"

- source: "http://xyz.com/my-mod.zip/#/my-folder/texture.png"
  target: "/path/to/target/directory/texture.png"

- source: "http://xyz.com/my-mod.zip/#/my-folder"
  target: "/path/to/target/directory"
---
Instructions or additional notes about the installation process.

Handling Hash-Routed Files

• The install.md file will support hash-routed URLs, enabling the sourcing of specific files within a ZIP file hosted externally.

3. Advantages

• Efficient Installation Process: Automating the creation of symlinks through install.md simplifies the mod installation process and allows the mod author to have complete control of exactly whats linked.
• Explicit Downloading: Hash-routed URLs offer a way to fetch the assets and unpack them, but the hash routing allows the enable/disable process to work independently.
• Clear Instructions: install.md provides clear, structured instructions, beneficial for both mod creators and users.
• Compatibility: This system maintains compatibility with existing YAML and Markdown-based structures in DCS Dropzone.

4. Implementation Considerations

• Security: Ensure secure handling of external URLs and file operations to prevent vulnerabilities.
• Documentation: Provide clear documentation for mod creators on how to use install.md.

The general workflow of the Mod Manager would be

A) Subscribe to a mod

• DCS Dropzone calculates the Asset URLs (Grab everything before # and dedupe)
• DCS Dropzone downloads all assets into a mod folder.
• DCS Dropzone unpacks any assets that are needed i.e. ZIPs

B) Enable a mod

• DCS Dropzone calculates FS paths for the assets based on deterministic behaviour (i.e. converts http://xyz.com/simple-script.lua to $MOD_ID/simple-script.lua and http://xyz.com/my-mod.zip/#/my-folder/texture.png to $MOD_ID/my-mod_zip/my-folder/texture.png
• DCS Dropzone creates symlinks between folders & files (as determined above) and their targets
• DCS Dropzone records the symlinks for reference later when removing.

C) Disable a mod

• DCS Dropzone removes all symlinks as stored earlier.

D) Unsubscribe to a mod

• DCS Dropzone disables if enabled
• DCS Dropzone deletes mod folder

[john681611]

• source: "http://xyz.com/simple-script.lua" target: "/path/to/target/directory/simple-script.lua"

This sounds good but doesn't account for the download link changing per release. We can't expect users to put in the full download link on each release it kinda kills the automated part of the release process

For repos where we can infer the actual link from a base then this is possible where mod-*.zip is a glob when grabbing assets

  source: "mod-*.zip/#/my-folder/script.lua"
  target: "/path/to/target/directory/simple-script.lua"

This gets worse when you think of the mess that can be made by manual releases using GoogleDrive one week and DropBox the next. What happens when a mod gets more files or less?

Its becoming more clear to me that this install config is gonna have to exist in the release/version object which is either manually uploaded to us or a known asset in a GH release.

[JonathanTurnock]

Yea so the GH integration would assemble this and commit it along with the release file and create the commit to the registry.

The install.md in the integrated repo would be a starter with placeholders and such that gets converted into a concrete install.md in the registry which in turn becomes the install.json.

Manual releases I don’t see anny issues people just author a new commit with concrete info.

I would say as files increase or decrease that’s why I though a subfolder. And the updating is just a process of automatically downloading disabling old enabling new and deleting old. But that can be easily the same as a swap folder.

[john681611]

I think a simple asset-mapping file is perfectly reasonable to ask devs to upload as part of a release or commit to the repository. This then solves a few issues.

• We can then support multiple versions of software at once while still being resistant to changes in mod installation
• We no longer need to do anything complex to figure out download paths (it's either full path or references another downloadable file in the release)
• This file can reference a version and therefore be stored as the version and a local enable/disable config that means its offline capable.

[JonathanTurnock]

Closing this one as I think we have a solid baseline now with the current install.md