GitHub source standard

Besides the Workshop, Downloads can fetch a work straight from a public GitHub repository. The repository is the package: the client reads package.json in the repository root, validates it against that manifest, then downloads the source archive of that commit. Authors need neither a release nor a zip asset.

This page covers what such a repository has to satisfy. The player-side steps are in Downloads, and the manifest fields are in the SCNexus package standard.

What the client does

Selecting Check and download makes the app fetch the content in four steps:

1. It resolves the commit for that reference from GitHub using the repository URL and branch, then pins it.
2. It reads the package.json in that commit's root (capped at 128 KiB), validates it against the SCNexus standard, and requires version to be a full semantic version.
3. Once validation passes it shows a preview (name, description, author, version, type, campaign, SCNID and whichever other fields the manifest carries); downloading only starts after you confirm.
4. It downloads the source archive of that commit into the download directory and marks it completed; the player then selects Install to enter the usual installation flow.

The key point is the pinned commit: the branch is resolved to a concrete commit at preview time and recorded, and the download uses that same commit, so new commits pushed to the branch after the check do not change what this download returns. To pick up a new version, create the task again.

What the repository has to satisfy

In plain terms: the repository root is the package root. Put Maps/, Mods/ and package.json directly under it; adding a src/ or pack/ folder for tidiness is read as the manifest not being in the root.

The repository may hold drafts, build scripts and a README.md that have nothing to do with installation: they come down with the archive, but only the resources and attachments declared in the manifest are installed.

How to write the address and branch

The repository URL must look like this:

https://github.com/owner/repository

• Only https:// is accepted — not http://, and not a branch path (/tree/main) or file path copied from the web interface.
• A trailing / is optional, and a trailing .git is removed automatically.
• The owner may contain letters, digits and - and must start with a letter or digit; the repository name may contain letters, digits and _ . - but cannot be ., .. or .git alone.
• GitHub Enterprise and other hosts are not supported — the prefix is fixed to github.com.

The branch may be a branch name, a tag or a commit, defaulting to main:

No path segment may start with . or end with . or .lock. A mistake is reported in the dialog straight away, asking for an address in the https://github.com/owner/repository form or for a branch name.

Size and structure

A GitHub source sets no size threshold of its own: there is no maximum archive size, and the Workshop's creator quota does not apply. As long as the repository can be pushed and the archive produced, the client will fetch it; the real limits are GitHub's own rules on file and repository size, which are not ours and are not checked here.

Only structural problems are rejected. Before extracting, the client walks the archive's entries; these checks have nothing to do with how large the work is and exist to block archives that cannot be extracted safely:

• Absolute paths, drive letters or .. in a path, or Windows reserved names (con, aux, com1 and the like).
• Two files differing only in case, which would overwrite each other on Windows.
• Paths nested unreasonably deep, or an enormous number of entries — usually a packaging tool that went wrong.
• A total extracted size far beyond any reasonable range (a hard line against archive bombs); ordinary campaigns and mods never come close.

When one of these hits, the dialog reports that the archive structure is unsafe; repack it with a normal directory depth. Reading the manifest has its own separate cap: the root package.json may not exceed 128 KiB, and a normal manifest is only a few KB.

When you do want to keep the download small, the reason is usually the player's experience rather than the checks: split the mod into a separate dependency package, declare it in dependencies, and let the installer place the upstream first.

Common failures and their causes

How it divides work with the Workshop

A GitHub source is a distribution channel, not a publishing channel: nothing is reviewed, there is no version history and no work number is produced. To appear in the Workshop and be downloadable by SCNID, a work still has to be created and uploaded in the creator center.

The two can coexist: keep developing in the repository and upload stable versions to the Workshop. Fill the scnid field with the number actually assigned to that project; the client will not treat the repository as a Workshop work just because the field is there.