Setting Up an AI-Assisted Game Project

Step 1: Organize Your Directory Structure by System

AI tools navigate your project the same way a new team member would: by reading directory names and file names to understand where different concerns live. A clear directory structure that separates game systems into distinct folders makes it obvious where rendering code, physics code, entity definitions, and UI code belong.

A standard structure for a web game project might look like: src/engine/ for the core game loop, timing, and lifecycle management. src/rendering/ for scene management, cameras, materials, and visual effects. src/physics/ for collision detection, rigid bodies, and physics world configuration. src/entities/ for entity definitions, components, and factory functions. src/systems/ for ECS systems or update managers. src/ui/ for HUD elements, menus, and in-game interface. src/audio/ for sound management and music. src/input/ for input handling and action mapping. src/state/ for game state management and save/load. src/utils/ for math utilities, helper functions, and shared constants.

Each directory should contain files that belong there and only there. A file named PlayerRenderer.ts belongs in src/rendering/, not in src/entities/ alongside the player entity definition. This discipline ensures that when the AI reads files from a directory, it gets a coherent picture of that system's patterns and conventions.

Avoid catch-all directories. A src/misc/ or src/helpers/ folder that accumulates unrelated utilities erodes the structural clarity that AI tools depend on. If a utility is used by multiple systems, place it in src/utils/ with a descriptive filename like vectorMath.ts or timeUtils.ts.

Step 2: Create Context Files for Each AI Tool

Every major AI coding tool supports a project context file that the AI reads before generating suggestions. These files are the most direct way to communicate your project's rules, architecture, and constraints to the AI.

For Cursor, create a .cursorrules file in your project root. For Claude Code, create a CLAUDE.md file. For GitHub Copilot, create .github/copilot-instructions.md. If you use multiple tools, create all of them. The content should be mostly the same across files, with minor formatting differences.

Structure the content in sections. Start with a project overview: engine name, version, game genre, and core architecture pattern (ECS, scene graph, MVC). Then list directory layout with one-line descriptions of each major directory. Add coding conventions: naming patterns, module structure, import style, error handling approach. Include specific constraints: what the AI should never do, which classes should not be modified directly, which patterns to always follow.

For game projects, include engine-specific rules. "Babylon.js mesh creation always goes through the MeshFactory class. Physics bodies use Havok plugin, never the deprecated CannonJS wrapper. All scene references must come from GameScene.getScene(), never stored as class properties. Asset loading uses the AssetManager queue pattern, never individual load calls."

Document your event system naming conventions if you use event-driven communication. "Events are namespaced with colon separators: entity:spawned, entity:destroyed, player:damaged, ui:menuOpened. Event payloads are typed with the IEventPayload interface. All event subscriptions include a cleanup reference for disposal." This prevents the AI from inventing its own event naming scheme.

Keep context files under 200 lines. The AI reads them on every interaction, and excessive length dilutes important information. Focus on rules that have the biggest impact on code quality and correctness.

Step 3: Add Strong Type Definitions

Type definitions give AI tools concrete information about your data shapes, function signatures, and interface contracts. For TypeScript game projects, this means defining interfaces and types for every significant data structure. For JavaScript projects, JSDoc annotations provide similar benefits.

Define interfaces for your core game objects. An entity interface specifies which properties every entity has (id, position, rotation, active status). Component interfaces define what data each component type contains. System interfaces describe the update signature and dependency requirements. Configuration interfaces document the shape of your settings objects.

Create a dedicated types file or directory for shared types. A src/types/ directory with files like entities.ts, components.ts, events.ts, and config.ts gives the AI a single place to find all your type definitions. When the AI needs to know the shape of a HealthComponent, it can look up the interface directly rather than inferring it from usage.

Type your event payloads explicitly. Rather than using generic objects for event data, define typed payload interfaces: IPlayerDamagedPayload with source, amount, damageType, and isCritical fields. The AI generates event handlers that correctly destructure these typed payloads rather than guessing field names.

Use enums or string literal unions for finite sets of values. GameState should be "menu" | "playing" | "paused" | "gameOver" rather than a bare string. DamageType should be "physical" | "fire" | "ice" | "lightning" rather than an untyped string. These constraints prevent the AI from generating code with invalid state values.

Step 4: Establish and Document Naming Conventions

Consistent naming throughout your project helps AI tools predict what names to use when generating new code. If your project uses camelCase for functions and PascalCase for classes consistently, the AI follows that pattern. If naming is inconsistent, the AI picks a random style for each generation.

Choose a naming pattern for each category and document it in your context files. Classes: PascalCase (PlayerController, PhysicsWorld, InventoryUI). Functions and methods: camelCase (updatePosition, calculateDamage, renderFrame). Constants: UPPER_SNAKE_CASE (MAX_HEALTH, GRAVITY_STRENGTH, TILE_SIZE). Events: colon-separated namespaces (entity:spawned, player:levelUp). Files: same as the primary export (PlayerController.ts exports PlayerController class).

Use descriptive, domain-specific names rather than generic ones. A function called updatePlayerMovementWithAccelerationAndFriction is verbose but leaves no ambiguity. A function called update tells the AI nothing about what it updates or how. For game code where dozens of systems all have update functions, descriptive names prevent the AI from confusing them.

Name your game parameters with units or context when possible. maxSpeedUnitsPerSecond is clearer than maxSpeed. jumpHeightTiles communicates that the value is measured in tile units. cooldownSeconds tells the AI the value is in seconds rather than milliseconds or frames. These names produce self-documenting AI suggestions.

Document abbreviations you use consistently. If "pos" always means position, "vel" always means velocity, "rot" always means rotation, and "dir" always means direction in your project, note that in your context file. The AI will use the same abbreviations in generated code rather than mixing full names and abbreviations.

Step 5: Set Up Build and Test Commands

AI agents like Claude Code can execute terminal commands to verify their work. Reliable build and test scripts let the agent catch errors immediately rather than leaving broken code for you to debug. Even for non-agent tools, having clear build commands documented in your context file helps the AI understand your development workflow.

Configure your package.json (or equivalent build configuration) with standard scripts: build for production compilation, dev for the development server, test for running the test suite, lint for code style checking, and typecheck for TypeScript type validation. Each command should exit with a meaningful error code so the AI agent knows whether the operation succeeded.

For game projects, the build step often includes additional processing: shader compilation, asset optimization, tilemap conversion, or level data validation. Document these steps so the AI understands what the build pipeline does and can diagnose build failures correctly.

Set up at least basic tests for your core game systems. Unit tests for damage calculation, inventory operations, state machine transitions, and pathfinding algorithms give the AI a way to verify that generated code does not break existing functionality. A test suite that runs in seconds provides rapid feedback during AI-assisted development sessions.

Include the build and test commands in your context file. "Build: npm run build. Dev server: npm run dev (runs on port 3000). Tests: npm test. Type check: npm run typecheck. Lint: npm run lint." This information lets the AI agent autonomously build, test, and fix its own output.

Step 6: Create Example Patterns for the AI to Follow

The most reliable way to get the AI to follow your conventions is to show it a working example. When you have a recurring pattern in your game (entity components, system update loops, event handlers, factory functions), make sure at least one clean, well-documented example of that pattern exists in your codebase.

If your entity components all follow a specific lifecycle (init, update, destroy), write one component that clearly demonstrates the full lifecycle with descriptive method implementations. The AI copies the pattern from this example when generating new components, including the method signatures, property initialization, and cleanup behavior.

For factory functions, create one that shows the complete creation flow: parameter validation, object construction, component attachment, event registration, and return. The AI replicates this exact flow for new factories rather than inventing its own structure.

Mark your example files explicitly. A comment at the top like "// Example pattern: standard game component with full lifecycle" helps both the AI and human developers identify reference implementations. You can also point to examples in your context file: "See src/entities/components/HealthComponent.ts for the standard component pattern."

Update your examples when your patterns evolve. If you refactor your component system from class-based to function-based, update the reference example immediately. Stale examples cause the AI to generate code in the old style while your project has moved on, creating inconsistency.