Go to file

Breezebuilder 9390e89633 feat: add proper version detection for repos with multiple immutable URLs for different mods (#290 )

Reopening after messing up #288.

## Motivation

The current version detection logic assumes that mods using
`automatic-version-check` either:
1. Use GitHub's automatic latest release URL
(`releases/latest/download/mod.zip`)
2. Link directly to repository HEAD (`archive/refs/heads/main.zip`)

However, some mod authors, like me, use **permanent release tag URLs**
like `releases/download/mod-name__latest/mod.zip` to provide stable
download links while still updating the underlying release. This pattern
is particularly common in **monorepos** where multiple mods share a
single repository.

## Problem

When a mod uses a permanent tag URL, the current script queries the
repository's overall latest release, which fundamentally diverge from
how releases in a monorepo work. This causes issues where:

- **All mods get the same version**: Every mod gets versioned as
whatever release was created most recently across the entire repository
- **False update notifications**: BMM detects "updates" when unrelated
mods are released
- **Broken update detection**: Actual updates to specific mods may not
be detected

## Solution

This PR adds support for permanent release tag URLs with minimal changes
by:

1. **Detecting the pattern**: URLs matching
`releases/download/{tag}/{asset}` or `releases/tag/{tag}` (excluding
`releases/latest/`)
2. **Querying specific tags**: Instead of `/releases/latest`, query
`/releases/tags/{specific-tag}`
3. **Using asset timestamps**: Generate versions based on the most
recent asset's `created_at` timestamp, this avoids generating updates
for simple renames in the asset.
4. **Maintaining compatibility**: All existing URL patterns continue to
work unchanged

### Key Design Decisions

- **Asset-agnostic**: Uses the most recently created asset instead of
searching for specific filenames, keeping it simple and efficient
- **Timestamp-based versioning**: Format `YYYYMMDD_HHMMSS` provides
human-readable, sequential versions

## Benefits

- **Enables monorepo workflows**: Authors can maintain multiple mods in
one repository with reliable update detection by updating specific tags
assets
- **Broader ecosystem support**: Works with any permanent tag naming
convention
- **Zero breaking changes**: Existing single-mod repositories continue
working identically

## Example

**Before**: All mods in `/balatro-mods` get version
`rebalanced-stakes__v1.2.8` (latest across entire repo)

**After**: 
- `qol-bundle` gets version `20240115_103042` (when `qol-bundle__latest`
tag has new asset)
- `rebalanced-stakes` gets version `20240116_140521` (when
`rebalanced-stakes__latest` tag has new asset)

This enables reliable update detection for each mod independently.

## Considerations
The `update_mod_versions` script currently uses the `created_at`
timestamp of the most recent asset to generate versions. This approach
is intentionally flexible and works with various ways of updating fixed
release tags, but it may be worth considering more opinionated
approaches in the future. For example, we could require semantic
versioning in release titles or extract changelogs from release bodies,
which would open up possibilities for additional features.

This implementation can also be extended to latest-release URLs with
little effort, since they just redirect to a specific release tag in the
API. Any future metadata extraction features could apply to both URL
patterns.

For now, this PR focuses on providing immediate compatibility with
minimal friction in the existing environment, while establishing a
foundation that can be built upon later.

2025-07-08 12:59:54 +10:00

.github

Revert repository url check for CI

2025-07-07 12:28:32 -03:00

media

for later

2025-01-01 18:50:14 +01:00

mods

feat: add proper version detection for repos with multiple immutable URLs for different mods (#290 )

2025-07-08 12:59:54 +10:00

schema

version meta field is always required again

2025-07-07 12:14:35 -03:00

.gitignore

add standard python .gitignore

2025-04-20 18:44:06 +02:00

LICENSE

Initial commit

2025-01-01 16:45:59 +01:00

README.md

version meta field is always required again

2025-07-07 12:14:35 -03:00

README.md

Balatro Mod Index Guide

This guide explains how to structure and publish your Balatro mods in the Balatro Mod Index repository. Follow the instructions below carefully to ensure your mod is properly added.

Directory Structure

Your mod should have the following structure inside the mods/ directory:

mods/
- Author@Modname/
  - thumbnail.jpg (optional but preferred)
  - description.md (required)
  - meta.json (required)

Example

For a mod titled "Pokermon" by "InertSteak":

mods/
- InertSteak@Pokermon/
  - thumbnail.jpg
  - description.md
  - meta.json

Required Files

1. description.md

A markdown file describing your mod's features, installation steps, and any additional details you wish to share.

2. meta.json

This file stores essential metadata in JSON format. Make sure you adhere to the valid categories and mod-loader options. Below is an example:

{
  "title": "Extended Cards",
  "requires-steamodded": true,
  "requires-talisman": false,
  "categories": ["Content"],
  "author": "Joe Mama",
  "repo": "https://github.com/joemama/extended-cards",
  "downloadURL": "https://github.com/joemama/extended-cards/releases/latest/extended-cards.zip",
  "folderName": "ExtendedCards",
  "version": "1.0.0",
  "automatic-version-check": true
}

title: The name of your mod.
requires-steamodded: If your mod requires the Steamodded mod loader, set this to true.
requires-talisman: If your mod requires the Talisman mod, set this to true.
categories: Must contain at least one of Content, Joker, Quality of Life, Technical, Miscellaneous, Resource Packs or API.
author: Your chosen username or handle.
repo: A link to your mod's repository.
downloadURL: A direct link to the latest version of your released mod. Using an automatic link to the latest release is preferred.
version: The version number of the mod files available at downloadURL.
folderName: (Optional) The name for the mod's install folder. This must be unique, and cannot contain characters < > : " / \ | ? *
automatic-version-check: (Optional but recommended) Set to true to let the Index automatically update the version field.
- Updates happen once every hour, by checking either your mod's latest Release, latest commit, or specific release tag, depending on the downloadURL.
- Enable this option only if your downloadURL points to an automatically updating source:
  - Latest release (recommended): Using a link to releases/latest
  - Latest commit: Using a link to the latest commit (HEAD)
fixed-release-tag-updates: (Optional) Set to true if your mod uses a fixed release tag and still wants to auto-update when modifying the underlying files. This can be useful for repositories with multiple mods, allowing you to have a release tag dedicated for each mod where you upload new versions. Note that:
- Requires automatic-version-check to also be set to true.
- The downloadURL must point to a specific release asset using a link such as https://github.com/author/repo/releases/download/my-release-tag/mod.zip.

3. thumbnail.jpg (Optional)

If included, this image will appear alongside your mod in the index. Maximum and recommended size is 1920x1080 pixels.

How to Publish

Fork the Balatro Mod Index Repository
Go to the main Balatro Mod Index repository on GitHub and click Fork to create your own copy.
Create a New Mod Directory
Under mods/, add a folder named Author@Modname (e.g., InertSteak@Pokermon).
Inside it, include:
- description.md (required)
- meta.json (required)
- thumbnail.jpg (optional but recommended)
Write Your Mod Description
Use description.md to explain what your mod does, key features, and any usage instructions.
Populate meta.json
Commit and Push
Commit your directory and files, then push them to your fork.
Open a Pull Request (PR)
From your fork, open a Pull Request to the main repository's default branch (e.g., main):

Title: "Add Author@Modname mod"
Description: Briefly describe your mod's purpose or any extra details.

Automated Checks
As soon as you open the PR, GitHub Actions runs the automated checks to ensure your mod meets the required standards. If any checks fail, you will need to address the issues before your PR can be merged.
Manual Review
A project maintainer or designated reviewer will review your PR to confirm it meets ethical, technical, and overall quality standards.
Merge
Once the automated checks and manual review pass, your PR will be merged. Your mod then becomes part of the Balatro Mod Index!

Once your submission is reviewed and approved, your mod will be added to the Balatro Mod Index!

Submission Policy

All submissions must be safe, legal, and appropriate for a general audience. This means:

No mods containing malware or spyware.
No copyrighted content that is used without permission.
No hateful, discriminatory, or offensive material.

By submitting your own mod to the Balatro Mod Index, you are agreeing to allow your mod to be displayed in and redistributed by Balatro Mod Manager. If you would like your content to be removed from the Balatro Mod Index at any point, please create an Issue or submit a Pull Request with the relevant content deleted.

Third-Party Submissions

Mods should ideally be submitted by their creators. If you would like to submit a mod on behalf of a mod's creator, please do so in a way that is considerate of the author, their creative works, and their time.

Mods will only be accepted on the Balatro Mod Index if they have been released under a redistribution-friendly license (such as GPL, MIT, MPL or similar), or if the mod's authors have given explicit and public permission. It is strongly encouraged to ask for permission before submitting other's mods to the Balatro Mod Index, regardless of license.

Before submitting mods created by other people:

Check that the mod is working on the most current version of the game, and has not been deprecated or abandoned.
Check that the mod's license allows redistribution by third parties - otherwise, ask permission from the creator.
Check the mod's requirements for Steamodded and Talisman, along with any other dependencies that should be listed in the description.
Check if the mod requires a specific installation folder name, and set the folderName parameter accordingly.
Check that the mod doesn't have any other special or unusual installation requirements.
Check if the mod has any promotional images that might be suitable for use as a thumbnail.

When submitting a mod on behalf of someone else, please link to the latest Release whenever possible rather than the latest repository HEAD. This helps to keep modded Balatro stable for more players, by only using tested releases instead of potentially untested in-development builds.

Thanks for contributing to the Balatro Mod Index and helping the community grow!