Assemble3

Wiki

Build games with AI: the Assemble3 AI Toolkit

The AI Toolkit is a kit that lets an AI agent (such as Claude Code, or another assistant that can run commands) turn an idea into a complete, tested game, delivered as an .a3p file that opens straight in the editor.

You write the request in plain language, and the AI designs the game, draws the images, makes the sounds, builds the events, tests it and hands over the file.

Example request: "Make a platformer where a frog hops between lily pads and collects coins. It has 3 lives, a score on screen and a game over screen. Text in Portuguese."

What is in the kit

File What for
Assemble3 AI Game Builder Guide (PDF, 106 pages) The manual the AI reads: project format, event rules, tested recipes and a list of everything in the editor.
a3lib.py A Python library to describe the game (objects, layouts, events) without hand-writing the JSON.
tools/validate.js Checks every instruction, parameter and expression against the real engine core (libGD) and counts the events.
tools/export.js Exports the game to HTML5.
tools/playtest.js Plays the game in a headless browser (Chromium), checks its state and takes screenshots.
tools/a3p.py Encodes and decodes .a3p files.
tools/meta.js and reference.json Lookup of every available condition, action and expression.
samples/ Three complete example games, with their tests.

How it works

The AI follows a nine-step process, described in the guide:

Step What happens
1. Design The request becomes mechanics, screens, objects, variables and an event plan within the plan's limit.
2. Art and sounds Images (Pillow) and sounds (numpy → WAV) are generated by code. The AI checks a contact sheet of the images.
3. Build The game is described in Python with a3lib.py.
4. Validate validate.js checks everything against the real engine.
5. Export export.js produces the real HTML5 export.
6. Play-test playtest.js plays the game and takes screenshots, which the AI looks at.
7. Iterate The AI fixes what is not right and repeats steps 4 to 6.
8. Encode a3p.py creates the final .a3p.
9. Deliver You get the file, a screenshot and a summary: controls, mechanics, variables to tweak and the event count.

A complete game in 25 lines

This is the guide's smallest game: click the box to score points.

from PIL import Image, ImageDraw
from a3lib import *
import os
os.makedirs('assets', exist_ok=True)
img = Image.new('RGBA', (120, 120))
ImageDraw.Draw(img).rounded_rectangle([4, 4, 115, 115], 20, fill=(0, 200, 180), outline='white', width=6)
img.save('assets/caixa.png')

p = Project('Click the Box', 960, 540)
p.image('assets/caixa.png')
p.add_object(simple_sprite('Caixa', 'caixa.png'))
p.add_object(text('TextoPontos', 'Score: 0', 36, (255, 255, 255)))
lay = p.layout('Game', background=(30, 30, 60), layers=['', 'UI'])
lay.instance('Caixa', 480, 270)
lay.instance('TextoPontos', 20, 20, 'UI')
lay.variables = [num('Pontos')]
lay.events = [
    COMMENT('Click the box to score points!'),
    E(clicked('Caixa'), [set_var('Pontos', '+', '1'), set_scale('Caixa', '=', '1.2')]),
    E([], [set_scale('Caixa', '=', 'max(1, Caixa.ScaleX() - 2 * TimeDelta())'),
           set_text('TextoPontos', '"Score: " + ToString(Pontos)')]),
]
p.save_json('box.json')

Then validate and encode:

node tools/validate.js box.json box.rt.json
python3 tools/a3p.py encode box.rt.json ClickTheBox.a3p

How to use it

  1. Download the kit and the guide (below) and put them in a working folder.
  2. Run bash tools/setup.sh once. It downloads the engine core (libGD) and checks the other dependencies.
  3. Open your AI assistant in the folder, give it the PDF guide and ask for the game.
  4. Take the .a3p and open it in the editor: ☰ or Open → File….

Requirements

  • Python 3 with Pillow (and numpy for sounds).
  • Node 22.
  • Playwright with Chromium, for the game tests.
  • To export and test the game, the kit needs the compiled game runtime (GDJS), which is part of the Assemble3 source code. Without it you can still build, validate and encode the .a3p, and test the game by opening it in the editor.

What the AI follows

The guide has rules that prevent the most common mistakes:

  • Every instruction gets all its parameters, in order.
  • Every variable used in an expression is declared first.
  • The project stays within the plan's event limit (250 by default).
  • The Platform behavior jumps with the up arrow.
  • Keys that change screens use key released.
  • It never delivers without validating, exporting and play-testing.
  • Text in Portuguese by default, no violence, art and fonts under free licences.

What the AI delivers

  • The encoded .a3p file.
  • A screenshot of the game running.
  • A summary with controls, mechanics, adjustable variables and the event count.
  • What it could not verify, such as exact behavior inside the editor interface.

Always review it. Open the game in the editor, play it and read the events. An AI-made game is a starting point for you to learn from and change: the events are the same ones you would write by hand.

Download

After opening an AI-made game, carry on with Events and Behaviors to understand and change what it built.