Introducing Structured Commands

GameCatalyst uses structured commands instead of free-form text. Every action has a specific format, defined parameters, and validation rules. You do not need to memorize commands — Vex handles them. But understanding the system helps you appreciate why results are so reliable.

What is a structured command?

Commands follow a category.action format:

• object.create — Creates a GameObject
• transform.set — Changes position, rotation, or scale
• file.read — Reads file contents
• scene.load — Loads a Unity scene
• workspace.find — Searches for files by pattern

Each command has defined parameters with types. You cannot pass text where a number is expected — validation catches it.

How commands work:

1. You say: “Create a red cube at 0, 5, 0”
2. Vex translates to object.create_primitive with name, type, and position parameters
3. GameCatalyst validates the command and parameters
4. If valid, routes to the correct handler and executes in Unity
5. Results return to Vex, who reports back in plain language

Why structured commands matter:

• Type safety: Parameters checked before execution
• Clear docs: Every command has a defined signature with examples
• Error prevention: Invalid commands rejected before causing problems
• Consistency: Same command always works the same way

Aliases: Many commands have shortcuts. folder.read can be called as ls or dir. Vex knows all aliases.

You never type commands yourself:

Here is the important part — you do not need to memorize or type these commands. You talk to Vex in natural language. You say things like “create a red cube” or “move the player up by 3 units.” Vex translates your words into the correct structured commands automatically. The command system exists under the hood to ensure precision and safety, but you interact with it through normal conversation.

What happens when a command is invalid:

If Vex sends a command with wrong parameters, GameCatalyst rejects it immediately and sends back an error message with the correct usage from WhatIs. Vex reads the correction and fixes the call on the next attempt. You rarely see this happen because Vex uses pre-command knowledge checks to verify unfamiliar commands first. But when it does happen, the self-healing system handles it automatically.

Two types of command invocation:

Management commands (like list_all_projects and select_project) are called directly. Engine commands (like object.create and file.read) are called through a wrapper: use_command("object.create", {parameters}). This distinction ensures engine commands only run after you have selected a project, preventing accidental operations on the wrong project.