godot2ka

Put a Godot 4 web game on Khan Academy.

It takes your Godot HTML5 export, uploads it to GitHub, and generates a single HTML file you paste into a KA webpage program. The heavy files (engine, game data) are served from GitHub via jsDelivr — Khan Academy itself only ever holds the small loader file.

1. Install

Requires Python 3.10+.

pip install git+https://github.com/SwankyMan88/godot2ka.git

2. Export your game from Godot

Project → Export → Web, with:

• Thread Support: OFF (required — threaded builds cannot run on KA)
• Extensions Support: OFF (unless you specifically need GDExtension)
• Export mode: Release (Debug builds are much larger and slower to load)

3. Create a GitHub repo for the game data

Go to https://github.com/new.

• Public (required — jsDelivr can't read private repos)
• No README, no .gitignore - This is optional. It doesn't really matter.

4. Run the wizard

godot2ka-wizard

It walks you through everything and asks before doing anything public:

1. Where your export is
2. What to call the game
3. Which GitHub repo to use
4. How much of the game should be visible on screen
5. A version tag for this build
6. Whether to push now

Accept the default for any prompt by pressing Enter. Ctrl+C cancels safely at any point.

5. Paste it into Khan Academy

1. Go to https://www.khanacademy.org/computer-programming/new/webpage
2. Select all the starter code and delete it
3. Paste the contents of the program.html the wizard made
4. Save

That's it — the program is playable.

Releasing an update later

Made changes in Godot? Re-export, then run godot2ka-wizard again and give it a new version tag (it'll suggest one). Push, then paste the new program.html into your existing KA program.

Always use a new tag for an update — reusing the old one can serve players a broken mix of old and new game files for several hours.

Controlling how much of the game is visible

The wizard asks for a "render scale." Above 1, the game draws more of the world so you can see farther; below 1, it draws less. You can also change this after publishing without rebuilding anything, by adding to the program's URL:

?scale=1.5

This only works if your project's stretch mode is set to disabled (Project Settings → Display → Window → Stretch → Mode). With other stretch modes, this setting only affects sharpness, not how much you can see.

Troubleshooting

Problem	Fix
"Wrong window size"	Add ?width=1066 to the end of the KA program's URL (try 1067 if that doesn't work)
Loading gets stuck partway	Wait a minute and reload — a freshly pushed version can take a moment to become available
SharedArrayBuffer is not defined	Re-export with Thread Support off
Game is silent	Click the Start game button that appears once loading finishes — browsers block sound until you interact with the page
Game renders small in a corner	In Godot: Project Settings → Display → Window → Stretch → Mode → canvas_items, Aspect → keep

If something else goes wrong, open the browser's developer console (F12) and check for red error text — that's the fastest way to find out what happened.

Advanced usage

Run the packer directly instead of the wizard, for scripting or CI:

godot2ka path/to/export --repo YOURUSER/my-game-files --title "My Game"

Flag	Purpose
--repo	GitHub repo storing the game data (required unless --base-url)
--ref	Version tag for this build (default main — see note above about tagging)
--title	Browser tab title
--heading	Loading-screen text (defaults to --title)
--render-scale	How much of the game is visible (default 1.0)
--ka-width	Width KA must report before starting (default 1066)
--out	Output directory (default dist)
--base-url	Serve game data from a URL you control instead of GitHub/jsDelivr — useful for testing locally

For the reasoning behind how this works — and why several obvious-looking simplifications would break it — see docs/HOW_IT_WORKS.md.