Document most of our manual methods for unpackaging

[GarboMuffin]

• the classic: Scratch.vm.stop(); URL.createObjectURL(await Scratch.vm.saveProjectSb3())
• using debugger to breakpoint on usePackagedRuntime to set that to false
• we seriously could automate this very easily. unfortunately, we wouldn't have any way to link to the best ways to automate it while following scratch guidelines

[GarboMuffin]

For full transparency, every manual unpackage request I handled since yesterday was handled by Claude. I spent a while with Claude describing how to unpackage projects, guiding it through a bunch, and we got this SKILL.md. This is entirely AI slop but it also works very well.

The language model approach has some nice things because it doesn't have to follow rigid code. You can give it a link from some random game website and it can attempt with some level of success to find where the game is, download it, figure out if it's a big HTML file or if it needs to get assets by hand.

There's a world where we replace the manual unpackaging request form with a "paste this into your LLM" type thing and then hide the instructions for manual unpackaging in there, or something. But that's a long ways out.

---

---
name: unpackage
description: How to unpackage Scratch/TurboWarp projects from URLs such as itch.io links
---

Step 1: Resolve the game URL

If given an itch.io URL (e.g., https://username.itch.io/game-name):

1. Fetch the page with curl -sL <url>
2. Search for html-classic.itch.zone/html/ anywhere in the page source — it may appear as a plain iframe src or HTML-encoded (e.g., " instead of ")
3. Extract the full URL: https://html-classic.itch.zone/html/<id>/index.html?v=<version>

If given a GameJolt URL (e.g., https://gamejolt.com/games/name/ID):

1. GameJolt's API is behind Cloudflare and hard to access via curl
2. Ask the user to open the game in their browser, then inspect the page to find the iframe src pointing to serve.gamejolt.net
3. The URL pattern looks like: https://serve.gamejolt.net/<token>/data/games/.../files/<id>/index.html
4. Use that URL directly — note the token is time-limited

If given a Cocrea.world URL (e.g., https://www.cocrea.world/@user/ProjectName):

1. Fetch the page with curl -sL <url>
2. Parse __NEXT_DATA__ JSON from the HTML
3. Extract projectLink from props.pageProps.creationData.creationReleaseResp.projectLink
4. Extract the assetId from the URL (the hex filename without .sb3)
5. Download the file — it's AES-256-CBC encrypted base64 text
6. Decrypt and repack with assets (see "Cocrea.world decryption" section below)
7. Skip directly to Step 3 (external references) — Cocrea sb3 files only contain project.json, assets are at https://assets.cocrea.world/user_projects_assets/{md5ext}

If given a direct URL to an HTML file, use it directly.

Fetch the resolved HTML:

curl -sL -o /tmp/game.html "<resolved_url>"

If the HTML is very large (>10MB), that's normal — packaged Scratch projects embed binary data.

Step 2: Extract the project

Run this inline Node.js script from the repo root (/home/thomas/Projects/unpackager):

const fs = require('fs');
const unpackage = require('./unpackager.js');

(async () => {
  const data = fs.readFileSync('/tmp/game.html');
  const result = await unpackage(data);
  const buf = Buffer.from(result.data instanceof ArrayBuffer ? result.data : result.data.buffer || result.data);
  fs.writeFileSync('/tmp/project.' + result.type, buf);
  console.log(result.type + ' — /tmp/project.' + result.type + ' (' + buf.length + ' bytes)');
})();

The unpackager auto-detects the format and outputs the correct project type. It handles all inline formats automatically:

• Base85 (progressive, multi-script, single — versions 1-4)
• Base64 data URIs (TurboWarp Packager, forkphorus, HTMLifier)
• HTMLifier initOptions and legacy formats
• Raw zip/sb3 files

Step 3: Handle external references

If the unpackager throws "project was packaged as a zip, but only the HTML file was provided", the project uses external references — assets are in separate files alongside the HTML.

1. Determine the base URL from the HTML page URL (everything before the last /).

2. Download project.json:

   BASE="<base_url>"
   curl -sL -o /tmp/project.json "$BASE/assets/project.json"
   # If that 404s, try: $BASE/project.json

3. Extract all asset references and download them:

   Run this Node.js script to collect every md5ext — costumes, sounds, AND fonts (.ttf/.otf):

   const fs = require('fs');
   const pj = JSON.parse(fs.readFileSync('/tmp/project.json', 'utf-8'));
   const assets = new Set();
   
   // Costumes and sounds from all targets
   for (const t of pj.targets) {
     for (const c of (t.costumes || []))
       assets.add(c.md5ext || `${c.assetId}.${c.dataFormat}`);
     for (const s of (t.sounds || []))
       assets.add(s.md5ext || `${s.assetId}.${s.dataFormat}`);
   }
   
   // Custom fonts (in extension metadata like customFonts arrays)
   // Search the entire JSON for md5ext references to font files
   const str = JSON.stringify(pj);
   for (const m of str.matchAll(/"md5ext":"([a-f0-9]+\.(?:ttf|otf))"/g))
     assets.add(m[1]);
   
   fs.writeFileSync('/tmp/assets.json', JSON.stringify([...assets]));
   console.log('Assets:', assets.size);

4. Download all assets in parallel:

   mkdir -p /tmp/assets
   node -e "require('/tmp/assets.json').forEach(a => console.log(a));" \
     | xargs -P4 -I{} curl -sL --retry 3 --retry-all-errors --retry-delay 1 -o "/tmp/assets/{}" "$BASE/assets/{}"
   echo "Downloaded: $(ls /tmp/assets | wc -l) files"

5. Create the .sb3 zip:

   const fs = require('fs');
   const path = require('path');
   const JSZip = require('./dependencies/jszip.min.js');
   
   const zip = new JSZip();
   zip.file('project.json', fs.readFileSync('/tmp/project.json'));
   for (const file of fs.readdirSync('/tmp/assets'))
     zip.file(file, fs.readFileSync(path.join('/tmp/assets', file)));
   
   zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' }).then(buf => {
     fs.writeFileSync('/tmp/project.sb3', buf);
     console.log(`Wrote ${(buf.length/1024/1024).toFixed(1)} MB (${Object.keys(zip.files).length} files)`);
   });

Step 4: Verify the output

ls -lh /tmp/project.sb3
unzip -l /tmp/project.sb3 | head -5 && unzip -l /tmp/project.sb3 | tail -1

Check that:

• File size is reasonable (at least a few KB, usually hundreds of KB to several MB)
• project.json exists in the zip
• Report the file size to the user

Step 5: Test in TurboWarp

Open the project in TurboWarp Desktop so the user can visually confirm it works:

turbowarp-desktop /tmp/project.sb3

Use the AskUserQuestion tool to ask the user if the project loaded correctly (yes/no) before proceeding to upload.

Step 6: Upload and share

Once the user confirms it works, upload to send.vis.ee using ffsend with maximum limits (20 downloads, 3 days):

ffsend upload -d 20 -e 3d /tmp/project.sb3

This prints a download URL. Share it with the user along with the original URL they provided, so they can match it to the right context.

Cleanup

After uploading, remove all temp files:

rm -rf /tmp/game.html /tmp/project.sb3 /tmp/project.json /tmp/assets.json /tmp/assets /tmp/script.js

Cocrea.world decryption

Cocrea (Gandi IDE) encrypts .sb3 files at rest on their CDN. The decryption key is derived from a hardcoded secret prefix concatenated with the assetId.

Finding the key if it changes: The secret is a short string stored in the Gandi IDE runtime JS bundle (the large 7ad223b3...js chunk). Search for the variable used in the AES encrypt/decrypt pair — it's a constant s in the closure containing AES.encrypt and AES.decrypt calls with enc.Base64.parse(s + t). As of 2026-03, the secret is KzdnFCBRvq3.

Decryption (Node.js, no dependencies):

const crypto = require('crypto');

function decryptCocrea(base64Data, assetId) {
  const secret = 'KzdnFCBRvq3';
  const keyBuf = Buffer.from(secret + assetId, 'base64');
  const key = keyBuf.slice(0, 32);
  const iv = keyBuf.slice(0, 16);
  const ciphertext = Buffer.from(base64Data, 'base64');
  const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv);
  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
  // Plaintext is comma-separated byte values
  return Buffer.from(decrypted.toString('utf-8').split(',').map(Number));
}

The assetId is the hex filename from the projectLink URL (e.g. 940443780668470a51324ee06b0738b6). The decrypted output is a zip containing only project.json — assets must be fetched separately from https://assets.cocrea.world/user_projects_assets/{md5ext} using the Step 3 process.

Three code paths (checked via first 8 bytes of downloaded data):

• [80,75,3,4,...] (PK magic) → already a valid zip, no decryption needed
• [55,122,188,175,...] (7z magic) → prepend PK header [80,75,3,4,10,0,0,0] to data after byte 8
• Otherwise → AES decrypt as above (this is the common case)

Important notes

• The HTML files can be very large (100MB+) because they embed all project assets — this is normal
• Only the external references case (Step 3) requires manual asset downloading — everything else is handled by the unpackager
• Always use md5ext references from the full JSON to catch fonts (.ttf, .otf) — they live in customFonts arrays in extension metadata, not in the usual costumes/sounds

[seif626]

Sorry but this is confusing, will you ever make a video guide in the future soon?

[ArcticNiko]

For full transparency, every manual unpackage request I handled [...]

Careful. Some Sprunki modders are insane and will include anti-unpackaging measures that log your IP and browser details for the sole purpose of intimidating you. If you unpackage one of Draker's mods, then it's a guarantee that it'll happen. I've also seen Draker give this tech out to coolskull212 for his Sprunki Shifted Retake mod as well.

Now, there are a few things to keep in mind:

1. Apart from Draker's mods and Shifted Retake (which was released almost a year ago), nobody else has done the same thing, meaning that this is very unlikely to happen anyway.
2. This is obvious to spot – look for suspicious fetch permission requests and custom extensions with obfuscated code or page-modifying functions that require being run unsandboxed
3. This only happens on itch.io projects, not Cocrea projects (where there's a function to make projects unremixable anyway)
4. Most of the people in the Sprunki community do actually find this unethical (which is why it doesn't happen in other mods), and Draker's reputation has actually been ruined as a result (alongside other reasons), so please don't take this as a representation of the entire Sprunki community!

Regardless, it's still something you should keep in mind while doing this. To protect myself, I use Windscribe VPN and Mullvad Browser while testing out .sb3s in PenguinMod. I have thought about retiring this setup lately and just opening it in Chrome unprotected since the odds of this happening are zero nowadays, but my guards are still high.

[seif626]

Isn't that..bypassable by removing a sketch extension on the project json (such as drakeryayhappy and the other one I don't remember)

[baksel12]

For full transparency, every manual unpackage request I handled [...]

Careful. Some Sprunki modders are insane and will include anti-unpackaging measures that log your IP and browser details for the sole purpose of intimidating you. If you unpackage one of Draker's mods, then it's a guarantee that it'll happen. I've also seen Draker give this tech out to coolskull212 for his Sprunki Shifted Retake mod as well.

Now, there are a few things to keep in mind:

1. Apart from Draker's mods and Shifted Retake (which was released almost a year ago), nobody else has done the same thing, meaning that this is very unlikely to happen anyway.
2. This is obvious to spot – look for suspicious fetch permission requests and custom extensions with obfuscated code or page-modifying functions that require being run unsandboxed
3. This only happens on itch.io projects, not Cocrea projects (where there's a function to make projects unremixable anyway)
4. Most of the people in the Sprunki community do actually find this unethical (which is why it doesn't happen in other mods), and Draker's reputation has actually been ruined as a result (alongside other reasons), so please don't take this as a representation of the entire Sprunki community!

Regardless, it's still something you should keep in mind while doing this. To protect myself, I use Windscribe and Mullvad Browser while testing out .sb3s in PenguinMod. I have thought about retiring this setup lately and just opening it in Chrome unprotected since the odds of this happening are zero nowadays, but my guards are still high.

yeah, that happened with me when i oppened a .sb3 file that i got decomopiled, i was lucky and it had no ip grabber, i should consider using my vpn...

[baksel12]

Isn't that..bypassable by removing a sketch extension on the project json (such as drakeryayhappy and the other one I don't remember)

most of them check based on your username, if its the creators one, it does not do anything, if not it activates... You can remove it in the code.

[seif626]

But yeah, most of them just check your username, and then executes "javascript("Text saying you decompiled")" and then it clones itself so fast it stops you deleting the thing

[ArcticNiko]

I'm aware of how to bypass the anti-unpackaging measures for Sprunked Final Version. I wasn't really focusing on that in my comment; rather, I was focusing on the risk of encountering such a thing, regardless of how easily bypassable it is.

[seif626]

I just hope this guide gets a video on it.. since well it's confusing

[GarboMuffin]

Careful. Some Sprunki modders are insane and will include anti-unpackaging measures that log your IP and browser details for the sole purpose of intimidating you

Thanks for the warning though that's really not a concern for me.

I only fully execute unpackaged projects in TurboWarp because I can trust there is no IP logging risk. If it's made for another engine, I generally don't test beyond checking that the JSON is parseable and it looks like all the assets are there (or I turn on a VPN first). If other engines have security bugs that allow IP logging, that's a problem for that engine and their users to deal with.

Some engines seem to believe that being able to IP log people in the editor is a feature. That's unfortunate, but nothing I can do about that.

I just hope this guide gets a video on it.. since well it's confusing

The guide is AI slop written by AI (based on a human walking through how to do it in several iterations) and intended to be consumed by AI. Very honest about that.

If you copy and paste that into Claude or ChatGPT with a link to a project, maybe it'll be able to follow the instructions for you. Not sure what the code execution abilities of the free tiers of those are though. I usually run this through a sandboxed Claude Code.

I don't foresee there being a guide because there are a lot of edge cases. And processing manual unpackager requests is a lot easier than it used to be with that prompt

[Mickmick21]

I used the slop guide to vibe code a shell script that does almost same thing with less dependencies. (i'm sorry i'm not that good at bash)

It needs the project.json currently but that may change.

It does work tho.
projectgen.sh

[seif626]

Is that for windows or linux

[ArcticNiko]

Is that for windows or linux

It's for Linux, but you should be able to run it on Windows using WSL or MingW.