Construct 3 Copilot

https://github.com/xhxiaiein/construct3-copilot
Admin
An AI-powered tool that generates Construct 3 event sheet JSON from natural language descriptions,...
Tokens:10,807
Snippets:100
Trust Score:8.1
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setup and Run Construct 3 Copilot

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/README.md

Commands to clone the repository, install dependencies, start the required RAG and clipboard services, and launch the Copilot.

```bash
# 1. Clone Copilot
git clone https://github.com/XHXIAIEIN/Construct3-Copilot.git
cd Construct3-Copilot

# 2. Auto-clone all dependencies + install pip packages
bash .claude/plugins/construct3-copilot/scripts/infra/setup.sh

# 3. Start services (each in its own terminal)
cd ../Construct3-RAG && python src/api.py
cd ../Construct3-Clipboard && python src/api.py

# 4. Run Copilot
cd ../Construct3-Copilot && claude
```

--------------------------------

### Usage Examples for Construct 3 Copilot

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/README.md

Examples of natural language prompts and the corresponding AI-generated output types.

```text
> Create a breakout game, paddle follows mouse

AI generates:
- layout.json  → Paste to: Project Bar → Layouts
- events.json  → Paste to: Event sheet margin
```

```text
> Add WASD 8-direction movement controls

AI generates events JSON → Paste to: Event sheet margin
```

```text
> Add a pause feature, press ESC to pause

AI generates events JSON → Paste to: Existing event sheet
```

--------------------------------

### Explain Behavior in RAG

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Query the RAG service to get explanations for Construct 3 behaviors, including their properties. This is useful for understanding how to implement specific game mechanics.

```bash
# Explain a behavior
python3 scripts/query/rag.py search "8direction behavior properties"
```

--------------------------------

### Correct ACE ID and Parameter Formatting

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Examples of correct ACE IDs, behavior types, and parameter structures to avoid common hallucination traps.

```javascript
// WRONG (does not exist)           // CORRECT (actual ID)
"set-angle-toward-position"      -> "set-angle" + "angle(x1,y1,x2,y2)" expression
"move-toward"                    -> MoveTo behavior or manual displacement
"EightDir"                       -> "8Direction" (use display name for behaviorType)
"set-speed" (8Direction)         -> "set-max-speed"
"on-click" (no params)           -> "on-click" requires "mouse-button" parameter
"toggle-boolean"                 -> "toggle-boolean-eventvar"
"compare-boolean"                -> "compare-boolean-eventvar"
"add-to"                         -> "add-to-eventvar"

// Example of correct behavior action
{
  "id": "simulate-control",
  "objectClass": "Player",
  "behaviorType": "8Direction",  // Use display name, not "EightDir"
  "parameters": {"control": "up"}
}

// Key codes are numbers
{"key": 32}   // Space
{"key": 87}   // W
{"key": 65}   // A
{"key": 37}   // Left arrow
{"key": 39}   // Right arrow

// Comparison operators are numbers
// 0=eq, 1=neq, 2=lt, 3=lte, 4=gt, 5=gte
{"comparison": 0, "value": "100"}  // equals 100
```

--------------------------------

### Get Information on Addon Types

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Query the RAG service, specifying multiple collections like 'addon_sdk' and 'scripting', to compare different addon types, such as the difference between behaviors and plugins.

```bash
# Get information about addon types
python3 scripts/query/rag.py search "behavior vs plugin difference" --collections addon_sdk,scripting
```

--------------------------------

### Run Full JSON Health Report

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Execute the health check script to get a full JSON report of service status. This is useful for detailed monitoring.

```bash
python3 scripts/infra/health.py
```

--------------------------------

### Enhance welcome.sh for Project Memory

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Initializes the project memory loading logic within the welcome script.

```bash
# 3b. Project memory (if .c3proj found)
C3PROJ=""
```

--------------------------------

### Search Addon SDK Documentation

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the RAG service with the 'addon_sdk' collection to search for documentation related to creating custom plugins and behaviors for Construct 3.

```bash
# Search addon SDK documentation
python3 scripts/query/rag.py search "create custom behavior" --collections addon_sdk
```

--------------------------------

### Search SDK Documentation for ACE Definition

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the RAG service with the 'addon_sdk' collection to find documentation on how to define Actions, Conditions, and Expressions (ACEs) in the 'aces.json' file for Construct 3 addons.

```bash
# Search SDK documentation
python3 scripts/query/rag.py search "plugin instance lifecycle" --collections addon_sdk
python3 scripts/query/rag.py search "define ACE in aces.json" --collections addon_sdk
```

--------------------------------

### Search SDK Documentation for Patterns

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the RAG service with the 'addon_sdk' collection to search for specific patterns or methods within the Construct 3 Addon SDK documentation, such as 'IWorldInstance methods' or 'editor property types'.

```bash
# Search for specific SDK patterns
python3 scripts/query/rag.py search "IWorldInstance methods" --collections addon_sdk
python3 scripts/query/rag.py search "editor property types" --collections addon_sdk
```

--------------------------------

### Update SessionStart Instruction

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Configures the SessionStart instruction to incorporate project memory and user profile context.

```bash
# 4. Instruction to Claude
echo "## SessionStart Instruction"
echo "用中文向用户打招呼。简短介绍当前服务状态，提示用户可以用哪些 skill。"
echo "如果有 User Profile，根据用户等级调整语气。"
echo "如果有 Project Memory，简要提及上次的项目进展。"
echo "不要逐字复读以上内容，用自然的方式表达。"
```

--------------------------------

### Locate and Load Project Memory

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Searches for a .c3proj file in the current or parent directory and displays the project memory if found.

```bash
# Search current dir and one level up for .c3proj
for D in "$PROJECT_ROOT" "$PARENT_DIR"; do
  FOUND=$(find "$D" -maxdepth 1 -name "*.c3proj" -print -quit 2>/dev/null)
  if [ -n "$FOUND" ]; then
    C3PROJ="$FOUND"
    break
  fi
done

if [ -n "$C3PROJ" ]; then
  C3PROJ_DIR=$(dirname "$C3PROJ")
  PROJ_MEMORY="$C3PROJ_DIR/.claude/memory/memory.md"
  if [ -s "$PROJ_MEMORY" ]; then
    echo "## Project Memory"
    grep -v '^<!--' "$PROJ_MEMORY" | head -40
    echo ""
  fi
fi
```

--------------------------------

### Repository File Structure

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/README.md

Detailed breakdown of the Construct3-Copilot repository contents.

```text
Construct3-Copilot/
├── .claude/
│   └── plugins/
│       └── construct3-copilot/       # Claude Code Plugin
│           ├── plugin.json
│           ├── CLAUDE.md
│           ├── skills/               # 4 skills (c3-create, c3-search, c3-validate, c3-addon)
│           └── scripts/              # RAG query, clipboard service, image generation
├── docs/                             # Design specs & references
├── tests/
│   ├── examples/                     # Full game examples (breakout, platformer)
│   ├── fixtures/                     # Minimal JSON fixtures (validation)
│   └── regressions/                  # Regression test cases
└── plans/                            # Implementation plans
```

--------------------------------

### List Actions for Plugin

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Query the RAG service to list all available actions for a specific Construct 3 plugin, such as 'Sprite'. This helps in understanding the capabilities of a plugin.

```bash
# Find all actions for Sprite plugin
python3 scripts/query/rag.py list "Sprite"
# Output: {"plugin": "Sprite", "actions": ["set-animation", "set-frame", "spawn-another-object", ...]}
```

--------------------------------

### Verify plugin.json Syntax

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Validates the JSON structure of the plugin configuration file using Python.

```bash
python3 -c "import json; json.load(open('.claude/plugins/construct3-copilot/plugin.json')); print('OK')"
```

--------------------------------

### Project Directory Structure

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/README.md

Visual representation of the project file hierarchy.

```text
../
├── Construct3-Copilot/           ← Claude Code plugin (you are here)
├── Construct3-RAG/               ← ACE schema + docs service
├── Construct3-Clipboard/         ← JSON generation + validation service
├── Construct-Addon-SDK/          ← Official SDK templates (Scirra)
├── Construct-Example-Projects/   ← Official examples (Scirra)
└── Construct3-Manual/            ← SDK documentation
```

--------------------------------

### Search RAG for Capability

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the RAG service to search for specific game development capabilities or features, such as detecting mouse clicks. This returns a list of relevant results with their IDs and descriptions.

```bash
# Search for a specific capability
python3 scripts/query/rag.py search "how to detect mouse click"
# Output: {"results": [{"id": "on-click", "objectClass": "Mouse", "description": "..."}]}
```

--------------------------------

### Check Service Availability

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Run this command to check if the RAG and Clipboard services are available. It provides a brief status update.

```bash
# Step 1: Check service availability
python3 scripts/infra/health.py --brief
# Output: RAG:+ Clipboard:+
```

--------------------------------

### Generate Clipboard JSON

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the Clipboard service to generate JSON for Construct 3 events. This command takes a JSON object describing the event structure, including triggers and actions.

```bash
# Step 3: Generate clipboard JSON
python3 scripts/generate/clipboard_service.py generate '{
  "type": "event_sheet",
  "events": [
    {
      "trigger": {"id": "key-is-down", "object": "Keyboard", "params": {"key": 37}},
      "actions": [{"id": "simulate-control", "object": "Player", "behavior": "Platform", "params": {"control": "left"}}]
    }
  ] }'
```

--------------------------------

### Run Brief Health Report

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Execute the health check script with the --brief flag for a concise, one-line summary of service availability. Indicates service status with '+' for available and '-' for down.

```bash
python3 scripts/infra/health.py --brief
```

--------------------------------

### Manage Clipboard Service

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the Clipboard service on port 8766 to generate and validate Construct 3 clipboard JSON data.

```bash
# Generate clipboard JSON from Intent IR
python3 scripts/generate/clipboard_service.py generate '{
  "type": "event_sheet",
  "events": [
    {"trigger": "on-start-of-layout", "actions": ["set-score-to-zero"]}
  ]
}'
# Output: {"success": true, "clipboard_json": {"is-c3-clipboard-data": true, ...}}

# Validate existing clipboard JSON
python3 scripts/generate/clipboard_service.py validate '{
  "is-c3-clipboard-data": true,
  "type": "events",
  "items": []
}'
# Output: {"passed": true, "errors": [], "warnings": []}

# Validate from a file
python3 scripts/generate/clipboard_service.py validate clipboard.json
# Output: {"passed": false, "errors": ["items[0].conditions[0] missing 'type'"]}

# Check service health
python3 scripts/generate/clipboard_service.py health
# Output: {"status": "ok", "version": "1.0.0"}

# Local validation without network (lite mode)
python3 scripts/generate/clipboard_service.py validate --local '{
  "is-c3-clipboard-data": true,
  "type": "events",
  "items": [{"eventType": "variable", "name": "Score", "type": "number", "initialValue": "0", "comment": ""}]
}'
# Output: {"passed": true, "errors": [], "warnings": [], "mode": "local"}
```

--------------------------------

### Commit Plugin Changes

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Stages and commits the updated plugin configuration.

```bash
git add .claude/plugins/construct3-copilot/plugin.json
git commit -m "feat(memory): add Stop hook for automatic memory extraction"
```

--------------------------------

### Query RAG for ACE IDs

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

In strict mode, query the RAG service to find ACE IDs for game logic. This step is mandatory for generating valid clipboard JSON. Use 'search' for general queries and 'verify' for specific ACE IDs with optional plugin context.

```bash
# Step 2: Query RAG for ACE IDs (strict mode - mandatory)
python3 scripts/query/rag.py search "keyboard movement"
python3 scripts/query/rag.py verify "key-is-down" --plugin keyboard
python3 scripts/query/rag.py verify "simulate-control" --plugin platform
```

--------------------------------

### Check Feature Support in RAG

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Query the RAG service to check if Construct 3 supports a particular feature, such as 3D rendering or multiplayer networking. This helps in planning project scope.

```bash
# Check if C3 supports a feature
python3 scripts/query/rag.py search "3d support"
python3 scripts/query/rag.py search "multiplayer networking"
```

--------------------------------

### Perform Local Pre-validation

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Run offline validation on clipboard JSON structures to catch common errors without network access.

```bash
# Validate a simple events JSON
python3 scripts/generate/prevalidate.py '{
  "is-c3-clipboard-data": true,
  "type": "events",
  "items": [
    {"eventType": "variable", "name": "Score", "type": "number", "initialValue": "0", "comment": ""}
  ]
}'
# Output: {"passed": true, "errors": [], "warnings": []}

# Catch invalid event type
python3 scripts/generate/prevalidate.py '{
  "is-c3-clipboard-data": true,
  "type": "events",
  "items": [{"eventType": "invalid-type"}]
}'
# Output: {"passed": false, "errors": ["items[0].eventType 'invalid-type' invalid"], "warnings": []}

# Validate from file
python3 scripts/generate/prevalidate.py tests/fixtures/events_basic.json
# Output: {"passed": true, "errors": [], "warnings": []}
```

--------------------------------

### Run Regression Tests

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/tests/regressions/README.md

Execute the test suite using pytest to verify fixes and ensure no regressions.

```bash
python -m pytest tests/
```

--------------------------------

### Verify Plugin Hook Structure

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Validates the plugin.json file to ensure the required hooks are correctly defined.

```bash
python3 -c "import json; d=json.load(open('.claude/plugins/construct3-copilot/plugin.json')); print('Hooks:', list(d['hooks'].keys()))"
```

--------------------------------

### Skill Level Definitions Table

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/specs/2026-04-03-memory-module-design.md

Defines the skill levels for users, ranging from L1 Beginner to L4 Advanced. Only the level code is stored, not the inference basis.

```markdown
| Level | Signal |
|-------|--------|
| L1 Beginner | Unfamiliar with event sheet concepts, needs step-by-step guidance |
| L2 Basic | Can use basic plugins/behaviors, needs ACE lookup assistance |
| L3 Proficient | Familiar with event system, needs help with complex logic and optimization |
| L4 Advanced | Uses scripting/SDK, needs architecture-level discussion |
```

--------------------------------

### Configure Stop Hook in plugin.json

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Defines the Stop hook with a prompt-based instruction set for Claude to extract and persist memory according to project rules.

```json
{
  "name": "construct3-copilot",
  "version": "2.1.0",
  "description": "Construct 3 game development assistant — generates clipboard JSON, validates output, guides addon development, and searches ACE documentation",
  "skills": [
    "skills/c3-create",
    "skills/c3-validate",
    "skills/c3-addon",
    "skills/c3-search"
  ],
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/infra/welcome.sh\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Before ending this session, extract and persist memory per the rules in ${CLAUDE_PLUGIN_ROOT}/CLAUDE.md § Memory Management.\n\n## Steps\n\n1. Review the conversation for extractable information (skill level signals, project context, resolved problems, user preferences).\n2. Skip: operational Q&A, info already in project files, single-session debug details, Copilot errors.\n3. If nothing worth extracting → do nothing, stop here.\n4. Classify each piece as **profile** (user-level) or **project** (project-level).\n5. For profile entries → read `${CLAUDE_PLUGIN_ROOT}/memory/profile.md`. If entry count >= 20, append the oldest entries to `${CLAUDE_PLUGIN_ROOT}/memory/archive/profile-archived.md` (create if needed), then remove them from profile.md. Append new entries using the format: `### [Title]\n[Content]\n_Recorded YYYY-MM-DD_`\n6. For project entries → find `.c3proj` in the working directory tree, read its `uniqueId`. Target file: `{project_root}/.claude/memory/memory.md`. If it doesn't exist, create it with header `# Project Memory — {project name} (uniqueId: {id})`. Same overflow/archive rules — archive to `{project_root}/.claude/memory/archive/memory-archived.md`. Append new entries.\n7. No personal identity info. No verbatim quotes. Abstract only.\n8. Do not announce what you extracted to the user — just write silently."
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### RAG Query API

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

The RAG service provides semantic search and exact lookups for Construct 3 ACE definitions, plugin capabilities, and SDK documentation. It runs on port 8765.

```APIDOC
## RAG Query API

### Description
Provides semantic search and exact lookups for Construct 3 ACE definitions, plugin capabilities, and SDK documentation.

### Method
GET (simulated via script execution)

### Endpoint
`http://localhost:8765/query` (conceptual, actual usage via script)

### Parameters
#### Query Parameters
- **mode** (string) - Required - The query mode (e.g., `search`, `lookup`, `list`, `verify`).
- **query** (string) - Required - The search term or ACE ID.
- **plugin** (string) - Optional - The plugin name for lookup, list, or verify modes.
- **collections** (string) - Optional - Specifies collections to search within (e.g., `addon_sdk`).
- **top_k** (integer) - Optional - Number of results to return for search mode.
- **scope** (string) - Optional - Scope for search (e.g., `eventsheet`).

### Request Example
```bash
# Search for collision detection ACEs
python3 scripts/query/rag.py search "collision detection"

# Exact lookup of a specific ACE ID
python3 scripts/query/rag.py lookup "set-animation" --plugin sprite

# List all ACEs for a plugin
python3 scripts/query/rag.py list "Platform"

# Verify an ACE ID exists before using it
python3 scripts/query/rag.py verify "simulate-control" --plugin 8direction

# Search SDK documentation for addon development
python3 scripts/query/rag.py search "plugin instance creation" --collections addon_sdk

# Advanced search with filters
python3 scripts/query/rag.py search "move" --plugin sprite --top-k 5 --scope eventsheet
```

### Response
#### Success Response (200)
- **results** (array) - List of search results (for `search` mode).
- **found** (boolean) - Indicates if an item was found (for `lookup`, `verify` modes).
- **ace** (object) - Details of the found ACE (for `lookup`, `verify` modes).
- **plugin** (string) - Name of the plugin (for `list` mode).
- **actions** (array) - List of actions for the plugin (for `list` mode).
- **conditions** (array) - List of conditions for the plugin (for `list` mode).
- **expressions** (array) - List of expressions for the plugin (for `list` mode).

#### Response Example
```json
{
  "results": [
    {
      "id": "on-collision-with-another-object",
      "objectClass": "Sprite",
      "description": "Triggered when the object collides with another object."
    }
  ]
}
```
```

--------------------------------

### Verify ACE ID Correctness

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the c3-validate skill to verify if a specific ACE ID is correct for a given plugin. If incorrect, it provides a suggestion for the correct ACE ID or method.

```bash
# Verify ACE IDs are correct
python3 scripts/query/rag.py verify "set-angle-toward-position" --plugin sprite
# Output: {"verified": false, "suggestion": "Use 'set-angle' + angle(x1,y1,x2,y2) expression"}
```

--------------------------------

### Memory Entry Format

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/specs/2026-04-03-memory-module-design.md

Each entry in a memory file follows this markdown format. The timestamp is used for age-based eviction when the entry count exceeds 20.

```markdown
### [Brief title]
[Content — abstract, not verbatim quotes]
_Recorded YYYY-MM-DD_
```

--------------------------------

### Construct 3 Paste Location Reference

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Mapping of output types to their required paste locations within the Construct 3 editor.

```markdown
| Output Type      | Paste To                          |
|------------------|-----------------------------------|
| layouts          | Project Bar → Layouts             |
| object-types     | Project Bar → Object types        |
| events           | Event sheet margin                |
| event-sheets     | Project Bar → Event sheets        |
| world-instances  | Layout view (select instances)    |
| conditions       | Event block conditions area       |
| actions          | Event block actions area          |

# Example output with paste instructions:
"""
Generated clipboard JSON:
{...json...}

Paste to: Event sheet margin
Manual verification: After pasting, run layout and confirm player moves with arrow keys.
"""
```

--------------------------------

### Clipboard Service API

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

The Clipboard service handles JSON generation from Intent IR and validation of existing clipboard JSON. It runs on port 8766.

```APIDOC
## Clipboard Service API

### Description
Handles JSON generation from Intent IR and validation of existing clipboard JSON, ensuring adherence to the Construct 3 clipboard format.

### Method
POST (conceptual, actual usage via script)

### Endpoint
`http://localhost:8766/clipboard` (conceptual, actual usage via script)

### Parameters
#### Command Line Arguments
- **command** (string) - Required - The operation to perform (`generate`, `validate`, `health`).
- **data** (string) - Required for `generate` and `validate` (when not using a file) - The Intent IR or clipboard JSON string.
- **file_path** (string) - Optional - Path to a JSON file for validation.
- **local** (boolean) - Optional - Enables local validation mode without network access.

### Request Example
```bash
# Generate clipboard JSON from Intent IR
python3 scripts/generate/clipboard_service.py generate '{ "type": "event_sheet", "events": [{"trigger": "on-start-of-layout", "actions": ["set-score-to-zero"]}] }'

# Validate existing clipboard JSON
python3 scripts/generate/clipboard_service.py validate '{ "is-c3-clipboard-data": true, "type": "events", "items": [] }'

# Validate from a file
python3 scripts/generate/clipboard_service.py validate clipboard.json

# Check service health
python3 scripts/generate/clipboard_service.py health

# Local validation without network (lite mode)
python3 scripts/generate/clipboard_service.py validate --local '{ "is-c3-clipboard-data": true, "type": "events", "items": [{"eventType": "variable", "name": "Score", "type": "number", "initialValue": "0", "comment": ""}] }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful (for `generate`).
- **clipboard_json** (object) - The generated clipboard JSON (for `generate`).
- **passed** (boolean) - Indicates if validation passed (for `validate`).
- **errors** (array) - List of validation errors (for `validate`).
- **warnings** (array) - List of validation warnings (for `validate`).
- **status** (string) - Service status (for `health`).
- **version** (string) - Service version (for `health`).
- **mode** (string) - Validation mode (e.g., `local`) (for `validate --local`).

#### Response Example
```json
{
  "success": true,
  "clipboard_json": {
    "is-c3-clipboard-data": true,
    "type": "events",
    "items": [
      {
        "trigger": {
          "type": "on-start-of-layout"
        },
        "actions": [
          {
            "type": "set-score-to-zero"
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### Clipboard JSON Structure for Layouts

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Defines the JSON structure for game scenes, including object types, layers, world instances, and embedded image data. Allows for the generation of full game levels.

```json
{
  "is-c3-clipboard-data": true,
  "type": "layouts",
  "families": [],
  "object-types": [
    {
      "name": "Player",
      "plugin-id": "Sprite",
      "isGlobal": false,
      "instanceVariables": [],
      "behaviorTypes": [
        {"behaviorId": "Platform", "name": "Platform"},
        {"behaviorId": "scrollto", "name": "ScrollTo"}
      ],
      "animations": {
        "items": [{
          "frames": [{
            "width": 32, "height": 32,
            "originX": 0.5, "originY": 0.5,
            "imageDataIndex": 0
          }],
          "name": "Default"
        }]
      }
    },
    {
      "name": "Ground",
      "plugin-id": "TiledBg",
      "behaviorTypes": [{"behaviorId": "solid", "name": "Solid"}]
    }
  ],
  "items": [{
    "name": "Level1",
    "layers": [
      {
        "name": "Game",
        "instances": [
          {
            "type": "Player",
            "behaviors": {
              "Platform": {"properties": {"max-speed": 300, "jump-strength": 600}}
            },
            "world": {"x": 64, "y": 624, "width": 32, "height": 32}
          },
          {
            "type": "Ground",
            "world": {"x": 0, "y": 656, "width": 1280, "height": 64}
          }
        ]
      }
    ],
    "width": 1280,
    "height": 720
  }],
  "imageData": [
    "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0..."
  ]
}
```

--------------------------------

### Query RAG Service

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Interact with the RAG service on port 8765 to search ACE definitions, lookup IDs, or query SDK documentation.

```bash
# Search for collision detection ACEs
python3 scripts/query/rag.py search "collision detection"
# Output: {"results": [{"id": "on-collision-with-another-object", "objectClass": "Sprite", ...}]}

# Exact lookup of a specific ACE ID
python3 scripts/query/rag.py lookup "set-animation" --plugin sprite
# Output: {"found": true, "ace": {"id": "set-animation", "type": "action", "params": [...]}}

# List all ACEs for a plugin
python3 scripts/query/rag.py list "Platform"
# Output: {"plugin": "Platform", "actions": [...], "conditions": [...], "expressions": [...]}

# Verify an ACE ID exists before using it
python3 scripts/query/rag.py verify "simulate-control" --plugin 8direction
# Output: {"verified": true, "ace": {"id": "simulate-control", ...}}

# Search SDK documentation for addon development
python3 scripts/query/rag.py search "plugin instance creation" --collections addon_sdk
# Output: {"results": [{"source": "addon-sdk/reference/...", "content": "..."}]}

# Advanced search with filters
python3 scripts/query/rag.py search "move" --plugin sprite --top-k 5 --scope eventsheet
```

--------------------------------

### Clipboard JSON Structure for Events

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Defines the JSON structure for game logic, including variables, event blocks with conditions and actions, comments, groups, and function blocks. Requires 'is-c3-clipboard-data: true' header and 'type: events'.

```json
{
  "is-c3-clipboard-data": true,
  "type": "events",
  "items": [
    {
      "eventType": "variable",
      "name": "Score",
      "type": "number",
      "initialValue": "0",
      "comment": ""
    },
    {
      "eventType": "block",
      "conditions": [
        {
          "id": "on-collision-with-another-object",
          "objectClass": "Player",
          "parameters": {"object": "Coin"}
        }
      ],
      "actions": [
        {
          "id": "destroy",
          "objectClass": "Coin",
          "parameters": {}
        },
        {
          "id": "add-to-eventvar",
          "objectClass": "System",
          "parameters": {"variable": "Score", "value": "1"}
        }
      ]
    },
    {
      "eventType": "block",
      "conditions": [
        {
          "id": "key-is-down",
          "objectClass": "Keyboard",
          "parameters": {"key": 37}
        }
      ],
      "actions": [
        {
          "id": "simulate-control",
          "objectClass": "Player",
          "behaviorType": "Platform",
          "parameters": {"control": "left"}
        }
      ]
    }
  ]
}
```

--------------------------------

### Commit Memory Integration

Source: https://github.com/xhxiaiein/construct3-copilot/blob/main/docs/superpowers/plans/2026-04-07-memory-module.md

Stages and commits the changes related to project memory loading.

```bash
git add .claude/plugins/construct3-copilot/scripts/infra/welcome.sh
git commit -m "feat(memory): load project memory in SessionStart hook"
```

--------------------------------

### Local Pre-validation

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

The prevalidate module provides offline validation for clipboard JSON structure, catching basic errors without network access.

```APIDOC
## Local Pre-validation

### Description
Provides offline validation for clipboard JSON structure, catching basic errors like missing headers, invalid event types, and missing ACE fields without requiring network access.

### Method
POST (conceptual, actual usage via script)

### Endpoint
N/A (local script execution)

### Parameters
#### Command Line Arguments
- **data** (string) - Required - The clipboard JSON string to validate.
- **file_path** (string) - Optional - Path to a JSON file for validation.

### Request Example
```bash
# Validate a simple events JSON
python3 scripts/generate/prevalidate.py '{ "is-c3-clipboard-data": true, "type": "events", "items": [{"eventType": "variable", "name": "Score", "type": "number", "initialValue": "0", "comment": ""}] }'

# Catch invalid event type
python3 scripts/generate/prevalidate.py '{ "is-c3-clipboard-data": true, "type": "events", "items": [{"eventType": "invalid-type"}] }'

# Validate from file
python3 scripts/generate/prevalidate.py tests/fixtures/events_basic.json
```

### Response
#### Success Response (200)
- **passed** (boolean) - Indicates if validation passed.
- **errors** (array) - List of validation errors.
- **warnings** (array) - List of validation warnings.

#### Response Example
```json
{
  "passed": true,
  "errors": [],
  "warnings": []
}
```
```

--------------------------------

### Validate JSON File

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Validate a JSON file containing Construct 3 clipboard data. This command checks for structural integrity and valid ACE IDs, reporting success or failure with detailed errors and warnings.

```bash
# Validate and show detailed errors
python3 scripts/generate/clipboard_service.py validate tests/fixtures/events_basic.json
# Output: {"passed": true, "errors": [], "warnings": []}
```

--------------------------------

### Validate Clipboard JSON

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Validate the generated clipboard JSON. This step is mandatory to ensure the JSON is structurally sound and contains valid ACE IDs. The '--local' flag can be used for lite mode validation, skipping RAG verification.

```bash
# Step 4: Validate output (mandatory)
python3 scripts/generate/clipboard_service.py validate '{...generated json...}'

# Lite mode: Skip RAG, use local validation only
python3 scripts/generate/clipboard_service.py validate --local '{...json...}'
# Warning: "Lite mode: ACE IDs not verified via RAG. Paste at your own risk."
```

--------------------------------

### Validate JSON with Errors

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Use the c3-validate skill to check existing clipboard JSON for errors. This command highlights structural issues and missing fields, providing specific error messages.

```bash
# Validate JSON with errors
python3 scripts/generate/clipboard_service.py validate '{
  "is-c3-clipboard-data": true,
  "type": "events",
  "items": [
    {"eventType": "block", "conditions": [{"objectClass": "System"}]}
  ] }'
# Output: {"passed": false, "errors": ["items[0].conditions[0] missing 'id'"]}
```

--------------------------------

### Pydantic Models for Clipboard JSON Validation

Source: https://context7.com/xhxiaiein/construct3-copilot/llms.txt

Utilizes Pydantic models for local validation of clipboard JSON data, defining structures for types, events, and ACE references. Imports necessary classes from the 'models' module.

```python
from models import ClipboardData, ACERef, EventItem, VALID_CLIPBOARD_TYPES, VALID_EVENT_TYPES
```

```python
# Valid clipboard types
print(VALID_CLIPBOARD_TYPES)
# {'events', 'conditions', 'actions', 'object-types', 'world-instances', 'layouts', 'event-sheets'}
```

```python
# Valid event types
print(VALID_EVENT_TYPES)
# {'comment', 'variable', 'group', 'block', 'function-block'}
```

```python
# Validate clipboard structure
clipboard = ClipboardData(**{
    "is-c3-clipboard-data": True,
    "type": "events",
    "items": []
})
# Passes validation
```

```python
# ACE reference validation
ace = ACERef(type="Sprite", id="set-animation", parameters={"animation": "\"Walk\""})
print(ace.model_dump())
# {'type': 'Sprite', 'id': 'set-animation', 'parameters': {'animation': '"Walk"'}, 'behaviorType': None}
```

```python
# Event item with conditions and actions
event = EventItem(
    eventType="block",
    conditions=[{"type": "System", "id": "on-start-of-layout"}],
    actions=[{"type": "System", "id": "set-eventvar-value", "parameters": {"variable": "Score", "value": "0"}}]
)
```
Tokens:
Raw