Distributing Your Pack

Ship · for creators. You've made a pack and tested it. This is how to package it into a Thunderstore-ready zip and publish it — Thunderstore being the standard distribution channel for Silksong mods.

You'll be able to: assemble the files Thunderstore expects, write a correct manifest.json, and upload a pack that installs cleanly for everyone else.

Before you start

A publishable pack needs:

• Your asset files, in the standard folder structure, under a Stitchwork/ folder.
• manifest.json — Thunderstore's required metadata file.
• icon.png — exactly 256×256, the listing's display icon.
• README.md — what your pack does (Thunderstore renders it on the listing).
• (optional) a CHANGELOG.md, screenshots, and layered source files for remixers.

Test the pack from a clean install first — a separate game folder or profile — following your own README. The most common shipping bug is "works on my machine" because of other packs or settings you forgot you had.

The package layout

Lay the pack out like this:

my-pack/
  manifest.json
  icon.png
  README.md
  CHANGELOG.md        (optional)
  Stitchwork/
    pack.json         (optional — your pack's Pack Manager name/author/version)
    Sprites/
    Spritesheets/
    Sounds/
    Text/
    ...

The inner Stitchwork/ folder is what the mod scans for assets (it also accepts a Patchwork/ folder, for packs authored against upstream Patchwork). Everything else is Thunderstore's packaging metadata.

The three metadata files sit at the root of the zip — not inside a subfolder. This is the single most common upload mistake. When you zip, select the contents of my-pack/ (the manifest.json, icon.png, README.md, and the Stitchwork/ folder), not the my-pack/ folder itself.

pack.json vs manifest.json — different files, different readers. manifest.json at the root is Thunderstore's (store listing, version, dependencies). The optional pack.json inside Stitchwork/ is Stitchwork's — it sets the name / author / version shown in the in-game Pack Manager (folder name is the fallback). Ship both; Stitchwork never reads manifest.json, and Thunderstore never reads pack.json.

manifest.json

{
  "name": "Hornet_Crystal_Variant",
  "version_number": "1.0.0",
  "website_url": "https://github.com/youruser/your-repo",
  "description": "A crystalline reskin of Hornet's primary outfit.",
  "dependencies": [
    "<BepInEx pack identifier — copy from its Thunderstore page>",
    "<Stitchwork identifier — copy from its Thunderstore page>"
  ]
}

Field by field:

• name — your pack's name. Letters, numbers, and underscores only (no spaces); it becomes part of the Thunderstore URL.
• version_number — semantic version MAJOR.MINOR.PATCH, e.g. 1.0.0. Thunderstore requires all three numbers, and you must bump it on every update (you can't re-upload the same version).
• website_url — a repo or social link. Optional, but it must be present as a key — use an empty string "" if you have none.
• description — one-line pitch, 250 characters max. Shown in listings.
• dependencies — the packages yours needs, each as the exact Thunderstore identifier in Namespace-Name-Version form (for example, the format looks like Author-PackName-1.2.3). Always include the BepInEx pack and Stitchwork.

Copy dependency strings; don't type them. Open each dependency's Thunderstore page and copy its identifier verbatim — the namespace, exact name, and a version that actually exists. A wrong or non-existent version string makes your pack fail to install. Because versions move, the copy-from-the-page habit is the durable one: re-copy when you update. (If you're targeting a Stitchwork build that isn't on Thunderstore yet, follow that release's own install notes for how players should get it.)

icon.png

• Exactly 256×256 px. Thunderstore rejects other sizes.
• PNG, with or without alpha.
• It should read at a glance — signature character, before/after, a recognisable silhouette. It's how people spot your pack in a long list.

README.md

Thunderstore renders this on your listing, so it's your storefront. Include:

• A one-line summary up top.
• Screenshots — before/after if it's visual.
• What it changes, specifically ("Hornet's idle and run animations", not "Hornet's appearance").
• What it doesn't change — sets expectations.
• Compatibility — does it work alongside other packs? Any known conflicts? (See Priority & Conflicts for how overlaps resolve.)
• Known issues or limitations.
• Credits, if you remixed someone else's work.

Zip and publish

1. Confirm the layout above, with the three metadata files at the package root.
2. Select the contents of your pack folder and compress them to a .zip. The zip's filename doesn't matter — Thunderstore reads the name and version from manifest.json.
3. Sign in to Thunderstore and open the Hollow Knight: Silksong community.
4. Upload Mod, choose your zip. Most of the listing form auto-populates from the manifest.
5. Submit. It usually appears within a few minutes.

Updating a published pack

• Bump version_number in manifest.json (you can't reuse a version).
• Re-zip with the new contents.
• Upload it as a new version — Thunderstore keeps the history.
• Note what changed in CHANGELOG.md so users know why to update.

Good habits

• Keep updates incremental. Small, focused versions are easier for users to adopt and easier for you to debug than a sweeping "2.0 changes everything".
• State your conflicts. If your pack obviously clashes with another popular one (you both reskin the same character), say so in the README. It saves everyone confusion — and the conflict rules explain what actually happens when two packs overlap.
• Don't bloat the download with sources. Ship .psd/.kra/.ase files in a separate "source" zip if you want to share them, not in the main package.
• Re-test from clean before every release, not just the first.

You can now turn a tested pack into a published one — correct manifest, legal icon, metadata at the zip root, dependencies copied from their own pages. The last thing worth getting right is how your pack behaves next to others: Priority & Conflicts.