Your First Task

This guide walks you through creating your first task with the Gamecraft Agent, from writing your initial prompt to reviewing the results and understanding the agent's workflow.

Getting Started

Prerequisites

Before starting your first task, ensure you have:

  1. Installed Gamecraft Agent from the VS Code marketplace

  2. Installed the Gamecraft Unity Plugin for your currenty Unity workspace

  3. Opened your Unity project in both Gamecraft and Unity

Opening the Agent

The Gamecraft Agent interface is located in Gamecraft's right-hand sidebar:

  1. Click the Gamecraft tab in the right sidebar, or

  2. Use the Command Palette (Cmd/Ctrl + Shift + P) and search for "Gamecraft: Focus on Gamecraft Agent View"

  3. The agent will open in a dedicated panel with a chat interface

Writing Your First Prompt

Understanding the Input Interface

The chat interface includes several key components:

  • Text area: Main input field for your instructions

  • Mode selector: Choose the agent's functionality (Ask mode to learn or Agent mode to code)

  • Model selector: Pick your preferred AI model (or default to Auto-select for best performance)

  • Enhance button (✨): AI-powered prompt improvement

  • Drag and Drop Context: Include files, images, etc. in your prompt by dragging/dropping into the chat input

Crafting Effective Prompts

Start with clear, specific instructions. Here are some examples for different task types:

Code Generation

Create a React component for a user profile card that displays:
- User avatar image
- Name and email
- Bio text
- Follow/Unfollow button
- Make it responsive and use Tailwind CSS

Code Analysis

Review the authentication system in this project and explain:
- How user login works
- What security measures are in place
- Any potential vulnerabilities you notice

Debugging

I'm getting a "Cannot read property 'id' of undefined" error when 
clicking the submit button on the Create page. Help me find and fix the issue.

Project Setup

Set up a new Express.js API with:
- TypeScript configuration
- User authentication with JWT
- Database connection to PostgreSQL
- Basic CRUD endpoints for a blog system

Using Context Mentions

The agent can reference specific files and contexts using the @ symbol (or via drag and drop):

  • Files: @src/components/Header.tsx - Reference specific files

  • Folders: @src/components/ - Include entire directories

  • Open tabs: @ then select from currently open files

  • Terminal: @terminal - Include recent terminal output

  • Problems: @problems - Reference VS Code problems panel

Example with context:

Review @src/utils/auth.ts and @tests/auth.test.ts to understand 
the current authentication flow, then add support for password reset 
functionality.

Understanding the Agent's Response

Response Flow

When you submit a task, the agent follows this workflow:

  1. API Request Started - Shows the agent is working

  2. Tool Planning - Agent decides what actions to take (read files, write files, etc.)

  3. Tool Execution - Agent performs file operations, commands, etc.

  4. Output Display - Shows results and asks for approval (if auto-approval not enabled)

  5. Completion - Task finishes or continues based on your feedback

Common Response Types

File Operations

The agent will show you exactly what changes it wants to make:

🔧 Wants to edit: src/components/UserCard.tsx

You'll see:

  • File path being modified

  • Diff view showing exact changes

  • Approve/Reject buttons for your decision (if auto-approve not enabled)

Terminal Commands

When the agent needs to run commands:

💻 Wants to run command: npm install react-router-dom

You can:

  • Approve to run the command

  • Reject to skip it

  • Modify the command in the input field before approving

Code Explanations

For analysis tasks, the agent provides:

  • Structured explanations with clear headings

  • Code snippets with syntax highlighting

  • Recommendations for improvements

  • Next steps suggestions

Interacting with Tool Requests

Approval Workflow

When auto-approval is disabled, the agent will ask for permission before:

  • Reading files in your project

  • Creating or modifying files

  • Retrying failed operations

  • Executing MCP tool requests

  • Delegating tasks to sub-agents

  • Running terminal commands

Approval Options

  • ✅ Approve: Execute the proposed action

  • ❌ Reject: Skip this action and continue

  • Modify: Edit the proposal before approving

  • Provide feedback: Add instructions in the text area

Auto-Approval Settings

For faster workflows, you can enable auto-approval for:

  • Read-only operations (safe file reading)

  • Write operations (file modifications)

  • Retry last operation (when something has failed)

  • MCP tools (external integrations)

  • Subtasks (delegate the task to a more specific type of agent)

  • Terminal commands (command execution)

    • By default, auto-approve for terminal commands is disabled

Configure these in Settings → Auto-Approve

Best Practices for Approval

  1. Review changes carefully - Check diffs before approving file edits

  2. Understand commands - Make sure you know what terminal commands do

  3. Start conservative - Reject uncertain operations initially

  4. Use checkpoints - Jump back to a previous checkpoint when necessary

  5. Provide feedback - Guide the agent if something looks wrong

Project Checkpoints

Understanding Checkpoints

Gamecraft Agent automatically creates checkpoints - snapshots of your project state - as you work. These provide a safety net that lets you experiment confidently and recover from unwanted changes.

When Checkpoints Are Created

  • Task Start: Baseline checkpoint when you begin a new task

  • File Changes: After the agent modifies, creates, or deletes files

  • Subagent Delegation: Before an agent delegates a task to a more specific agent

  • Command Execution: When terminal commands or MCP tool calls complete successfully

Checkpoint Indicators

Look for checkpoint markers in your conversation:

  • 📸 Initial Checkpoint: Your project's starting state

  • 📸 Progress Checkpoint: Automatic saves after changes

Using Checkpoints

Viewing Changes

To see what changed between checkpoints:

  1. Find a checkpoint marker in your conversation

  2. Click "View Differences"

  3. Review the diff showing:

    • Green: Added content

    • Red: Removed content

    • Modified files: Line-by-line changes

    • File operations: Created, deleted, or renamed files

Restoring Previous States

If you want to undo changes and go back to an earlier state:

  1. Locate the checkpoint you want to restore

  2. Click "Restore Checkpoint"

  3. Choose your restoration type:

Files Only: Reverts your files but keeps the conversation history

  • Good for: Testing different approaches

  • Preserves: All chat messages and context

Complete Restore: Reverts files AND removes conversation after that point

  • Good for: Starting fresh from a specific point

  • Warning: This permanently deletes subsequent messages

Managing Your Task

Task Controls

The task header provides several options:

  • 📊 Context Window: Shows token usage and current task

  • 🗜 Condense Context: Summarize the current context into a smaller context window

    • This can be useful to decrease costs or when you are reaching an agent's context window limit

  • 📤 Export: Download the complete conversation

  • 🗑️ Delete: Remove the task from history

  • ❌ Close: End the current task and start fresh

Monitoring Progress

Token Usage

  • Input tokens (↑): What you and the environment sent to the AI

  • Output tokens (↓): What the AI generated

  • Cache reads/writes: For models supporting prompt caching

  • Total cost: Running cost estimate

Context Management

The progress bar shows context window usage. When it's full:

  • Condense Context: Summarize older messages to free space

  • Start New Task: Begin fresh with clean context

Providing Feedback

You can guide the agent's work by:

Mid-Task Adjustments

That looks good, but can you also add error handling 
for the API calls?

Course Corrections

Actually, let's use a different approach. Instead of 
Redux, let's use React Context for state management.

Approval with Modifications

When approving tool use, you can add specifications:

Approve, but make sure to include TypeScript types 
for all the component props.

Understanding Results

Success Indicators

A successful task typically shows:

  • ✅ Completion message from the agent

  • File changes applied with no errors

  • Working code that runs without issues

  • Clear next steps if applicable

Common Issues and Solutions

Permission Errors

If file modifications fail:

  • Check file permissions in your workspace

  • Ensure files aren't locked by other applications

  • Verify you have write access to the target directories

API Limitations

If the agent hits context limits:

  • Use Condense Context to summarize older messages

  • Start a New Task for complex multi-step projects

  • Break large requests into smaller, focused tasks

Code Errors

If generated code has issues:

  • Provide specific error messages to the agent

  • Ask for targeted fixes rather than complete rewrites

  • Review dependencies and make sure they're installed

Tips for Success

Effective Communication

  • Be specific: "Add a login form" vs "Add a login form with email, password, remember me checkbox, and client-side validation"

  • Provide context: Reference relevant files, requirements, or constraints

  • Set expectations: Mention coding standards, frameworks, or patterns to follow

Project Organization

  • Clear structure: Well-organized projects help the agent navigate better

  • Descriptive names: Use meaningful file and folder names

  • Documentation: Keep README files and comments up to date

Building Workflows

Effective Gamecraft Agent usage involves:

  1. Start Small: Begin with focused, specific tasks

  2. Iterate: Build on successful results step by step

  3. Document: Keep track of effective prompts and patterns

  4. Customize: Adjust settings and modes for your workflow

Continuous Integration

  • Version control: Commit changes regularly to track progress

  • Code review: Treat agent output like any other code contribution

  • Testing: Verify generated code works as expected

  • Refinement: Don't hesitate to ask for improvements or corrections

By following this guide, you'll be ready to effectively collaborate with the Gamecraft Agent on your development projects. Remember that the agent is designed to be a helpful assistant—provide clear guidance, review its work carefully, and don't hesitate to provide feedback to get the best results.

Next Steps

The best way to improve your success while coding with Gamecraft Agent is to improve the context provided to the agent in each request. We've provided some resources to help you improve your prompts and better understand agent context:

Practice makes perfect. You will become better at prompting Gamecraft Agent the more times you work with it.

Advanced Features

Once comfortable with basic tasks, explore:

PreviousUnity Tilde FilesNextUnderstanding Context

Last updated