Home > Tasks > Games > GameLevelDesignTask

GameLevelDesignTask

Generates production-ready game level designs with comprehensive documentation, including layout, encounters, pacing analysis, and player guidance.

Side-Effect Safe GPT-4 Preferred Category: Games

⚙️ TaskConfig.json


{
  "level_name": "The Obsidian Vault",
  "game_type": "metroidvania",
  "level_theme": "dungeon",
  "level_duration_minutes": 15,
  "difficulty_tier": "hard",
  "include_boss_encounter": true
}

→

👁️ User UI

# Level Design: The Obsidian Vault

[S] -- [Z1] -- [Z2]
|
[P1] -- [B]

✔ Phase 1: Level structure created (9 zones)

✔ Phase 2: 6 encounters designed

✔ Phase 3: Pacing curve analyzed (Intensity: 82/100)

✔ Phase 4: 15 collectibles placed

Live Results Showcase

Explore actual level design artifacts generated by this task in the Cognotik workspace.

Field	Type	Description
`level_name` *	String	The name of the level.
`game_type`	String	The type of game (e.g., 'platformer', 'shooter', 'puzzle', 'rpg', 'metroidvania'). Default: `"platformer"`.
`level_duration_minutes`	Int (5-30)	Target duration in minutes (5-30). Default: `10`.
`difficulty_tier`	String	tutorial, easy, medium, hard, expert. Default: `medium`.
`player_count`	Int	Number of players (1-8). Default: `1`. (2+ for multiplayer).
`level_theme`	String	Level theme (e.g., 'forest', 'dungeon', 'city', 'space_station'). Default: `"dungeon"`.
`pacing_style`	String	steady, escalating, varied. Default: `escalating`.
`include_boss_encounter`	Boolean	Whether to include a final boss. Default: `false`.
`include_puzzles`	Boolean	Whether to include puzzle elements. Default: `true`.
`include_secrets`	Boolean	Whether to include secret areas. Default: `true`.
`include_collectibles`	Boolean	Whether to include collectibles. Default: `true`.
`generate_difficulty_variants`	Boolean	Whether to generate difficulty variants for accessibility. Default: `false`.
`include_visual_layout`	Boolean	Whether to include ASCII visual layout. Default: `true`.
`input_files`	List<String>	Optional glob patterns for context (e.g. `*/.kt`).

Phase 1: Level Structure

Generates the macro-layout, including zones, connections, and an ASCII visual representation of the map.

Phase 2: Encounter Design

Populates zones with combat, puzzles, and environmental challenges, including enemy composition and rewards.

Phase 3: Pacing Analysis

Calculates intensity curves, identifies the climax location, and strategically places rest points.

Phase 4: Content Placement

Adds collectibles and secret areas based on the theme and difficulty tier.

Phase 5: UX & Guidance

Defines implicit (environmental) and explicit (markers) player guidance systems.

Phase 6: Difficulty Variants

Generates optional balance adjustments for Easy, Hard, and Expert modes for accessibility.

Phase 7: Final Assembly

Compiles all phases into a comprehensive Markdown document, generates HTML/PDF exports, and provides a summary of generation statistics.

Orchestration Boilerplate

Directly instantiate the task within an existing orchestration context.


val task = GameLevelDesignTask(
    orchestrationConfig = config,
    planTask = GameLevelDesignTask.GameLevelDesignTaskExecutionConfigData(
        level_name = "Crystal Caves",
        game_type = "platformer",
        difficulty_tier = "medium",
        include_boss_encounter = true
    )
)
orchestrator.runTask(task)

Embedded Execution (Headless)

Use the UnifiedHarness to run the task in a CI/CD or CLI environment.


val harness = UnifiedHarness(serverless = true, openBrowser = false)
harness.start()

harness.runTask(
    taskType = GameLevelDesignTask.GameLevelDesign,
    executionConfig = GameLevelDesignTask.GameLevelDesignTaskExecutionConfigData(
        level_name = "The Obsidian Vault",
        game_type = "metroidvania",
        level_theme = "dungeon",
        level_duration_minutes = 15
    ),
    workspace = File("./game-project")
)

Test Case Example (JSON)

A standard test case for validating level generation logic.


{
  "level_name": "Neon District",
  "game_type": "shooter",
  "level_theme": "cyberpunk",
  "level_duration_minutes": 12,
  "difficulty_tier": "hard",
  "player_count": 4,
  "pacing_style": "varied",
  "include_boss_encounter": true,
  "include_secrets": true,
  "generate_difficulty_variants": true,
  "input_files": ["docs/lore/neon_district.md", "src/mechanics/ShootingSystem.kt"]
}

LLM Prompt Segment


GameLevelDesign - Generate complete game level designs with layout, pacing, and encounters
  ** Optionally, list input files (supports glob patterns) to be examined for context
  ** Specify level name and game type (platformer, shooter, puzzle, rpg, etc.)
  ** Set target duration and difficulty tier
  ** Configure player count (single or multiplayer)
  ** Choose level theme and visual style
  ** Include boss encounters, puzzles, secrets, and collectibles
  ** Define pacing style (steady, escalating, varied)
  ** Generate difficulty variants for accessibility
  ** Produces complete level design with ASCII visualization
  ** Includes encounter progression, pacing analysis, and player guidance
** Ideal for game development, level design documentation, and prototyping