godot2ka

Put a Godot 4 game on Khan Academy.

You made a game in Godot. This tool takes the exported files and turns them into something you can paste into a Khan Academy program. You answer a few plain-English questions, and it does the rest.

If you get stuck at any point, skip to Troubleshooting near the bottom.

---

What you'll need before starting

• Your game, exported from Godot as a web (HTML5) game. If you haven't done this yet, see step 2 below.
• A GitHub account (free) — sign up at https://github.com/join if you don't have one.
• Python installed on your computer. Most people already have it. To check: open a terminal (see below) and type python --version. If you see a version number, you're set. If you see an error, install it from https://www.python.org/downloads/ — on the install screen, tick the box that says "Add Python to PATH" before clicking Install.

What's "a terminal"?

It's a plain text window where you type commands instead of clicking things.

• Windows: press the Start key, type powershell, press Enter.
• Mac: press Cmd+Space, type terminal, press Enter.

Every gray box below is something you type into that window, then press Enter.

---

1. Install the tool

Open a terminal and run:

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

Wait for it to finish (a few seconds). If it prints anything ending in Successfully installed godot2ka..., it worked.

"pip is not recognized" / "command not found"

Python isn't installed, or wasn't added to PATH. Reinstall it from https://www.python.org/downloads/ and make sure to check "Add Python to PATH" during setup. Then close and reopen your terminal and try again.

---

2. Export your game from Godot

In the Godot editor: Project → Export → Web.

Before clicking Export, set these two things (they're on the export screen):

Setting	Value	Why
Thread Support	OFF	Khan Academy can't run multi-threaded web games. If this is on, the game won't start there at all.
Export mode (top of window)	Release, not Debug	Debug exports are much bigger and slower to load for players.

Export it into its own empty folder somewhere you'll remember, e.g. C:\Users\you\Desktop\MyGameExport.

---

3. Create a place on GitHub to store the game

Your game's files are too big to fit inside a Khan Academy program directly, so they live on GitHub instead, and Khan Academy loads them from there.

1. Go to https://github.com/new
2. Give it any name, e.g. my-game-files
3. Set it to Public — this is required, or the game won't load
4. Leave everything else as-is and click Create repository

You don't need to put anything in it yourself — the tool does that for you in the next step. Just keep the page open, you'll need the name.

---

4. Run the wizard

Back in your terminal:

godot2ka-wizard

It asks you a series of questions, one at a time. Here's what each one wants:

It asks	What to type
Export directory	Paste the folder path from step 2 (e.g. C:\Users\you\Desktop\MyGameExport)
Game name / Browser tab title	Whatever you want players to see
Repository	The GitHub repo from step 3, as YourUsername/repo-name (e.g. SwankyMan88/my-game-files)
renderScale	Just press Enter to accept the default — you can change this later without redoing anything
Output directory	Just press Enter to accept the default
Tag for this build	Just press Enter to accept the suggestion
Push the game data to GitHub now?	Type y and press Enter

If a question shows something in [brackets], that's the default — just press Enter to use it.

The first time it pushes to GitHub, your browser or terminal may ask you to sign in to GitHub. That's normal — approve it.

When it finishes, it prints something like:

Then, on Khan Academy:
  1. https://www.khanacademy.org/computer-programming/new/webpage
  2. Select all the starter code (Ctrl+A) and delete it
  3. Paste the whole of dist\program.html
  4. Save

Keep that terminal window open — you'll need the file path in the next step.

---

5. Put it on Khan Academy

1. Open https://www.khanacademy.org/computer-programming/new/webpage (log in first if you aren't already)
2. Click inside the code editor, press Ctrl+A (select all), then Delete
3. Open the file the wizard mentioned (dist/program.html, inside wherever you ran the command from) in a text editor, select everything in it (Ctrl+A), copy it (Ctrl+C)
4. Click back in the Khan Academy editor and paste (Ctrl+V)
5. Click Save

Your game is now live. Open the program and try it.

---

Updating your game later

Made changes in Godot? Do this:

1. Export again from Godot (same settings as step 2)
2. Run godot2ka-wizard again, pointing it at the new export
3. When it asks for a version tag, just press Enter to accept the suggestion — don't reuse an old one, or players may see a broken mix of old and new files for a while
4. Copy the new program.html into your existing Khan Academy program the same way as step 5, and Save again

---

Making more or less of the game visible

While running the wizard, you'll be asked for a "render scale." Bigger numbers show more of the game world at once; smaller numbers show less.

You can also try different values after publishing, without running the wizard again — just add this to the end of your Khan Academy program's URL:

?scale=1.5

Try a few values (like 1, 1.5, 2) and see which looks best.

This only has a visible effect if, in Godot, Project Settings → Display → Window → Stretch → Mode is set to disabled. Any other setting there means this only affects sharpness, not how much you can see.

---

Troubleshooting

Problem	What to do
Page says "Wrong window size"	Add ?width=1066 to the end of the Khan Academy program's URL. If that doesn't help, try ?width=1067 instead.
It's stuck on a loading bar and never finishes	Wait a minute, then reload the page — a version you just published can take a moment to become available everywhere.
Console mentions SharedArrayBuffer	Go back to Godot and re-export with Thread Support turned off (step 2).
The game is silent	Click the Start game button that appears once loading finishes — browsers block sound until you click something on the page.
The game looks tiny, stuck in a corner	In Godot: Project Settings → Display → Window → Stretch → Mode → set to canvas_items, and Aspect → keep. Re-export and republish.
pip or godot2ka-wizard says "not recognized"	See the install troubleshooting note in step 1.
Something else	Press F12 in your browser to open developer tools, click the Console tab, and look for red text — that usually explains what went wrong.

---

Advanced: running it without the wizard

If you want to script this or skip the questions, you can call the tool directly with flags instead:

godot2ka path/to/export --repo YourUsername/repo-name --title "My Game"

Flag	Purpose
--repo	GitHub repo storing the game data (required unless using --base-url)
--ref	Version tag for this build (default main — see the tagging note above)
--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 Khan Academy must report before starting (default 1066)
--out	Output directory (default dist)
--base-url	Serve game data from a URL you control instead of GitHub — for local testing

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