Construct3-RAG

Construct3-RAG

English | 中文

Construct3-RAG is the reference data of Construct 3 (affiliate link) for AI agents. It holds every condition, action, expression and effect as the editor defines them, in two languages, as JSON files that an agent reads directly. It also holds the example index, the editor's language packs, the TypeScript definitions of the scripting API and Scirra's guide to the project format. A pipeline refreshes them from the editor's CDN each release.

The tools that make games from this data, the construct3-agent-plugin skill, its prompts and the Claude Code plugin construct3, live in Construct3-Agent-Skills. That repository builds its plugin from a clone of this one.

[!IMPORTANT] This repository holds data only, not the tools to build. To create or change a Construct 3 project, consult the Construct3-Agent-Skills repository, follow its README, and use its scripts to validate. Do not write a project from this data and general knowledge alone. You may miss unsupported values, and the editor will refuse to open the project.

Clone that repository beside this one, as the related repositories are, so that its scripts read this clone's data/: git clone https://github.com/XHXIAIEIN/Construct3-Agent-Skills ../Construct3-Agent-Skills.

To look a Construct 3 fact up in the data, see Look something up. To change this repository, read AGENTS.md.

Make a game

Install Git and Python 3.10 or later, then run these two commands as written, from any folder:

git clone https://github.com/XHXIAIEIN/Construct3-Agent-Skills $HOME/Construct3/Construct3-Agent-Skills
python $HOME/Construct3/Construct3-Agent-Skills/scripts/bootstrap.py --project MyGame

They clone that repository, the related repositories and the MyGame project into $HOME/Construct3, and install the skill in MyGame. The README of Construct3-Agent-Skills says what the skill does, how to install its Claude Code plugin, and what its scripts read, write and reach. The plugin carries a copy of this repository's data, so a plugin user does not need to clone this repository (Construct3-RAG).

Look something up

Read the files under data/. In the paths below, {locale} is one of the languages in c3-schemas/_index.json, such as en-US:

Field names match the Construct CDN. Structural fields such as id, scriptName, category and the parameter types are the same in every locale. So an ACE found in one locale has the same id in every other locale. Here is a condition from en-US/plugins/sprite.json:

{
  "id": "is-animation-playing",
  "list-name": "Is playing",
  "display-text": "Is animation {0} playing",
  "scriptName": "IsAnimPlaying",
  "category": "animations",
  "params": { "animation": { "type": "animation", "name": "Animation", "desc": "..." } }
}

The same id in another locale has that language's list-name, display-text and parameter names. docs/guide/data-format.md explains every field, with a worked example. Section 2 of AGENTS.md is the procedure that an agent follows, including deprecated ACEs and example projects.

The files of System and of the shared ACEs, plugins/system.json and plugins/_common.json, are too long for most file tools to read at once. Such a tool shows only the first part of a file, so an ACE after that part looks missing. With the Construct3-Agent-Skills clone beside this one, its lookup script reads them whole, and --rag . makes it read this clone's data:

python ../Construct3-Agent-Skills/plugin/skills/construct3-agent-plugin/scripts/lookup_ace.py --rag . System wait

It prints each match with its parameters, its wording and the JSON to write, and the official examples that use it.

Related repositories

Lookup service (optional)

A program that queries over HTTP can get the same data from a lookup service on your machine. The service is a deterministic keyword lookup that runs offline. It needs Python 3.11 or later:

pip install -r src/requirements.txt
python scripts/setup.py          # http://localhost:8765/playground

docs/guide/quick-start.md gives the setup options. docs/guide/api-reference.md gives the /search and /health endpoints and their responses.

Project structure

AGENTS.md               AI agent entry point
.claude/                Claude Code ACE lookup sub-agent and polish workflow
data/                   Committed reference data, read directly
  c3-schemas/           ACE definitions and effects, one folder per locale
  c3-examples/          Example project metadata
  c3-example-usage/     Which examples use each ACE
  c3-lang/              CDN language packs
  c3-ts-defs/           TypeScript scripting interfaces
  c3-guides/            Scirra's guide to the project format
  c3-new-project/       The editor's empty project, copied for a new game
src/                    Optional lookup service (see src/AGENTS.md)
scripts/                Lookup service setup, data refresh and maintenance tools (see scripts/AGENTS.md)
tests/                  Offline pytest suite
docs/guide/             User docs
docs/dev/               Contributor docs
docs/decisions/         Decision records
.github/workflows/      Checks on every push to main and every pull request, data update automation

Credits

Data from Construct 3 by Scirra Ltd, fetched from the editor CDN. Construct 3 is a trademark of Scirra Ltd.

MIT