Prompt Engineering Guide

Effective prompting is crucial for getting the best results from the Gamecraft Agent.

This guide teaches you how to craft prompts that leverage the agent's Unity-specific knowledge, development capabilities, and AI-powered features to maximize productivity and code quality.

Understanding Prompt Engineering

What is Prompt Engineering?

Prompt engineering is the art and science of crafting input messages that guide AI models to produce desired outputs. With coding assistants like Gamecraft Agent, well-engineered prompts can mean the difference between getting exactly what you need and spending time clarifying or correcting the results.

Why It Matters for Game Development

Game development involves complex systems, specific design patterns, and domain-specific knowledge. Unity development adds another layer of complexity with its component-based architecture, asset pipeline, and platform-specific considerations. Effective prompting helps the agent understand:

• Your project's architecture and constraints

• The specific Unity patterns you're using

• Performance requirements for your target platform

• Integration points with existing systems

Core Prompting Principles

1. Be Specific and Clear

Poor: "Make this script better"

Make this script better

Better: "Optimize this PlayerController script for mobile performance, focusing on reducing Update() calls and implementing object pooling for projectiles"

Optimize this PlayerController script for mobile performance. Specifically:
- Reduce Update() calls by using events or coroutines where appropriate
- Implement object pooling for projectile instantiation
- Cache frequently accessed components
- Add performance monitoring comments

2. Provide Context and Constraints

Poor: "Create a dialogue system"

Create a dialogue system

Better: "Create a branching dialogue system compatible with Unity's Localization package, supporting 2D portrait animations and audio playback"

Create a branching dialogue system with these requirements:
- Compatible with Unity's Localization package for multi-language support
- Support for 2D character portraits with animation states
- Audio playback integration for voice acting
- Save/load functionality for dialogue progress
- Node-based editor integration (if using existing graph tools)
- Target platform: Mobile (consider UI scaling)

3. Specify Output Format

Vague: "Explain how this works"

Explain how this works

Clear: "Create detailed code comments and a markdown summary explaining this state machine's flow, including a sequence diagram"

Please analyze this state machine and provide:
1. Detailed inline code comments explaining each state transition
2. A markdown summary with:
   - State diagram in ASCII or mermaid format
   - Flow explanation for each possible path
   - Performance considerations
   - Usage examples
3. Suggestions for debugging and testing each state

Unity-Specific Prompting

Leveraging Unity Knowledge

The Gamecraft Agent has deep Unity knowledge. Reference Unity-specific concepts directly:

Implement a ScriptableObject-based event system following Unity's recommended patterns:
- Use CreateAssetMenu for designer accessibility
- Implement UnityEvent<T> for type-safe callbacks
- Include OnValidate() for editor-time validation
- Follow Unity's naming conventions for public fields
- Add [Tooltip] attributes for designer guidance

Component and GameObject Patterns

Create a modular weapon system using:
- Component composition instead of inheritance
- Strategy pattern for different weapon types
- Unity's built-in collision detection
- Integration with Unity's new Input System
- Support for both 2D and 3D implementations

Performance-Aware Prompting

Optimize this enemy AI script for 100+ concurrent enemies:
- Use Unity's Job System where applicable
- Implement LOD system for AI complexity
- Cache NavMeshAgent components
- Use object pooling for pathfinding requests
- Profile memory allocations in Update loops

Effective Prompt Structures

The STAR Framework

Use this structure for complex requests:

Situation: Current project state and context Task: What you want to accomplish Action: Specific steps or approach Result: Expected outcome or format

Situation: Working on a 2D platformer with existing player movement
Task: Add wall-jumping mechanics that feel responsive
Action: Extend current PlayerController, add wall detection, implement coyote time
Result: Smooth wall-jump with visual feedback and sound integration points

Multi-Part Prompts

Break complex requests into numbered parts:

Please help me implement a save system:

1. Create a SaveData ScriptableObject that serializes:
   - Player progress (level, stats, inventory)
   - Game settings (audio, graphics)
   - Achievement state

2. Implement SaveManager with:
   - Async save/load operations
   - Backup system for corrupted saves
   - Platform-specific save locations

3. Add UI integration:
   - Save slot selection
   - Progress indicators for async operations
   - Error handling with user feedback

Iterative Refinement

Start broad, then refine:

First prompt: "Create a basic inventory system for an RPG"
Follow-up: "Add drag-and-drop functionality with visual feedback"
Refinement: "Implement stack splitting and right-click context menus"
Polish: "Add accessibility features and keyboard navigation"

Working with Tilde Files

Leveraging Bi-Directional Compilation

When working with Unity-specific prompts, reference the tilde file system:

Update the PlayerHealth.cs~ file to include:
- Damage reduction calculation based on armor stats
- Health regeneration over time
- Death animation triggers
- Integration with existing UI health bar

Ensure the changes sync properly with the Unity project and maintain
compatibility with the existing PlayerController dependencies.

Collaborative Workflows

Review my current GameManager.cs~ file and suggest improvements for:
- Better separation of concerns
- State management patterns
- Memory leak prevention
- Unit testing capabilities

Please make the changes directly to the tilde file and explain each
modification so I can understand the reasoning.

Context Optimization Strategies

Front-Loading Important Information

Place critical details early in your prompt:

Working with Unity 2023.2, targeting mobile platforms, using URP:

Implement a shader for 2D sprite outlines that:
- Works with Sprite Renderer components
- Supports dynamic color changes at runtime
- Maintains 60fps on mid-range Android devices
- Integrates with existing lighting system

Referencing Previous Context

Based on the PlayerController we created earlier, now add:
- Double jump mechanics
- Ground slam attack
- Particle effects for landing impacts

Maintain the existing input handling and animation integration points.

Efficient Information Density

Refactor for mobile performance:
- Reduce draw calls (batching, atlasing)
- Optimize physics (rigidbody sleeping, collision layers)
- Memory management (object pooling, texture compression)
- Battery efficiency (fixed timestep, frame rate limiting)

Advanced Prompting Techniques

Chain of Thought Prompting

Guide the agent through logical steps:

Let's build a quest system step by step:

1. First, analyze what data structures we need for:
   - Quest definitions
   - Player progress tracking
   - Conditional branching

2. Then design the interfaces for:
   - Quest givers and completers
   - Progress notifications
   - Save system integration

3. Finally, implement the UI components:
   - Quest log display
   - Objective tracking
   - Completion animations

Walk through your reasoning for each step.

Role-Based Prompting

As an experienced Unity technical artist, review this shader code for:
- Performance optimization opportunities
- Cross-platform compatibility issues
- Best practices for mobile rendering
- Integration with Unity's rendering pipeline

Focus on practical improvements that a technical artist would prioritize.

Constraint-Based Prompting

Design a dialogue system with these strict limitations:
- Maximum 2MB memory footprint
- No reflection or dynamic code generation
- Must work in Unity WebGL builds
- Backwards compatible with Unity 2021.3

Explain how each constraint affects your design decisions.

Common Prompting Mistakes

Mistake 1: Assuming Context

Poor: "Add the usual error handling" Better: "Add try-catch blocks for file I/O operations and null reference exceptions, with user-friendly error messages logged to Unity's Console"

Mistake 2: Vague Success Criteria

Poor: "Make it faster" Better: "Reduce frame time from 20ms to 16ms, targeting 60fps on iPhone 12"

Mistake 3: Overloading Single Prompts

Poor: "Create a complete multiplayer shooter with networking, AI, weapons, maps, UI, and progression system" Better: Break into focused prompts for each system

Mistake 4: Ignoring Platform Constraints

Poor: "Add realistic water physics" Better: "Add simplified water physics suitable for mobile devices, using vertex displacement instead of complex fluid simulation"

Debugging and Troubleshooting Prompts

When Results Don't Match Expectations

1. Clarify Requirements:

The weapon switching system you created doesn't match what I expected.
I need weapons to switch with scroll wheel input, show preview UI,
and maintain the current weapon's ammo count. Can you revise?

1. Request Explanation:

Explain why you chose a Dictionary over a List for weapon storage
in the previous implementation. What are the trade-offs?

1. Provide Specific Feedback:

The animation transitions are too slow. Change the crossfade duration
from 0.5s to 0.1s and add root motion dampening for smoother movement.

Best Practices Summary

Do's

• ✅ Start with clear objectives and constraints

• ✅ Reference Unity-specific patterns and conventions

• ✅ Specify target platforms and performance requirements

• ✅ Break complex requests into manageable parts

• ✅ Provide context about your project architecture

• ✅ Use technical terminology accurately

• ✅ Request explanations for learning

Don'ts

• ❌ Assume the agent knows your project's specifics

• ❌ Use vague terms like "better" or "optimize"

• ❌ Overload single prompts with multiple complex requests

• ❌ Ignore platform-specific considerations

• ❌ Forget to specify output format preferences

• ❌ Skip providing error messages or symptoms

Example Template

Use this template for complex Unity development requests:

**Context**: [Your project type, Unity version, target platform]

**Objective**: [What you want to achieve]

**Current State**: [What exists now, what's working/broken]

**Requirements**:
- [Specific requirement 1]
- [Specific requirement 2]
- [Performance/platform constraints]

**Integration Points**: [How this connects to existing systems]

**Output Format**: [Code comments, documentation, file structure, etc.]

**Success Criteria**: [How to know when it's working correctly]

Measuring Prompt Effectiveness

Quality Indicators

• First-try Success: Did the output match your expectations immediately?

• Code Quality: Is the generated code following best practices?

• Completeness: Did the response address all parts of your request?

• Context Awareness: Did the agent consider your project's constraints?

Iterative Improvement

Track what prompting strategies work best for your project:

• Keep a log of effective prompt patterns

• Note which technical details improve results

• Document project-specific context that helps

• Refine your prompting style based on outcomes

Remember: Great prompts lead to great code. Invest time in crafting clear, specific prompts, and you'll see significantly better results from the Gamecraft Agent.