Cognotik | GenerateSpriteSheetTask

⚙️ GenerateSpriteSheetTaskExecutionConfigData


{
  "files": ["assets/hero_walk.png"],
  "metadata_file": "assets/hero_walk.json",
  "task_description": "A pixel art warrior walking animation, 4 frames, side view, 16-bit style"
}

→

👁️ Session UI Output

Step 3: Sprites Extracted

✔ Generated assets/hero_walk.png

✔ Generated assets/hero_walk.json

Test Workspace Browser

Browse the output directory for the GenerateSpriteSheetTask test case. Explore actual artifacts generated by the GenerateSpriteSheetTask in the test workspace.

Configuration Parameters

Field	Type	Description
`files` *	List<String>	The sprite sheet image file to be created. Must end with `.png`.
`metadata_file` *	String	The JSON metadata file to be created. Must end with `.json`.
`task_description`	String	Detailed description of the sprites to generate (e.g., style, frame count, perspective).

Output Metadata Schema

The generated JSON file follows this structure:


{
  "sprites": [
    { "name": "walk_0", "x": 0, "y": 0, "width": 32, "height": 32 },
    ...
  ],
  "description": "General description of the sheet content"
}

Task Execution Flow

Image Generation: Uses ImageProcessingAgent to create a sprite sheet on a solid Magenta (#FF00FF) background. This ensures high contrast for the extraction phase.
Transparency Processing: Implements a custom Soft Keying algorithm. It calculates the Euclidean distance in RGB space from the magenta background to apply smooth alpha blending for anti-aliased edges.
Vision Analysis: The ParsedImageAgent (Vision LLM) analyzes the generated image to identify distinct sprite boundaries, assigning descriptive names and pixel-perfect bounding boxes.
Asset Export:
- Master Sheet: Saves the full .png with transparency.
- Metadata: Writes the .json coordinate file.
- Individual Sprites: Extracts and saves each identified sprite as a standalone file in a sub-directory.
- Debug View: Generates a verification image with red bounding boxes.

Programmatic Invocation

Use the UnifiedHarness to execute this task in a headless environment (CI/CD or CLI tools):


import com.simiacryptus.cognotik.apps.general.UnifiedHarness
import com.simiacryptus.cognotik.plan.tools.file.GenerateSpriteSheetTask
import com.simiacryptus.cognotik.plan.tools.file.GenerateSpriteSheetTask.GenerateSpriteSheetTaskExecutionConfigData
import java.io.File

val harness = UnifiedHarness(serverless = true)
harness.start()

harness.runTask(
    taskType = GenerateSpriteSheetTask.GenerateSpriteSheet,
    executionConfig = GenerateSpriteSheetTaskExecutionConfigData(
        files = listOf("assets/warrior_walk.png"),
        metadata_file = "assets/warrior_walk.json",
        task_description = "A 4-frame pixel art warrior walking animation, side view"
    ),
    workspace = File("./my-game-project"),
    autoFix = true // Automatically save files to disk
)

Agentic Orchestration

Add this task to your OrchestrationConfig to allow the AI Planner to use it during complex jobs:

Embedded Execution (Headless)

To invoke this task programmatically using the UnifiedHarness (as detailed in the Embedding Guide):


import com.simiacryptus.cognotik.plan.tools.file.GenerateSpriteSheetTask
import com.simiacryptus.cognotik.plan.tools.file.GenerateSpriteSheetTask.GenerateSpriteSheetTaskExecutionConfigData
import com.simiacryptus.cognotik.plan.tools.TaskTypeConfig

fun generateAssets(harness: UnifiedHarness, projectDir: File) {
    val executionConfig = GenerateSpriteSheetTaskExecutionConfigData(
        files = listOf("assets/sprites/warrior_animations.png"),
        metadata_file = "assets/sprites/warrior_animations.json",
        task_description = "A 16-bit pixel art warrior, 4-frame walk cycle, side view, holding a glowing sword."
    )

    harness.runTask(
        taskType = GenerateSpriteSheetTask.GenerateSpriteSheet,
        typeConfig = TaskTypeConfig(), // Use default model settings
        executionConfig = executionConfig,
        workspace = projectDir,
        autoFix = true // Automatically commit files to disk
    )
}

Test Case Example

Example of a structured test case for validating asset generation:


{
  "test_name": "Warrior Sprite Generation",
  "config": {
    "files": ["test_output/warrior.png"],
    "metadata_file": "test_output/warrior.json",
    "task_description": "Simple 4-frame idle animation for a slime monster"
  },
  "assertions": [
    "file_exists: test_output/warrior.png",
    "json_contains: sprites",
    "min_sprites: 4"
  ]
}

Orchestration Setup


val config = OrchestrationConfig(
    availableTasks = listOf(
        GenerateSpriteSheetTask.GenerateSpriteSheet,
        // ... other tasks
    ),
    smartModel = OpenAIModels.GPT4o.asApiChatModel()
)

Prompt Segment

This text is injected into the LLM context to describe the tool's capabilities:


GenerateSpriteSheet - Create a sprite sheet image and corresponding JSON metadata
  * Generates an image containing multiple sprites based on a description
  * Automatically identifies sprite locations (x, y, width, height)
  * Outputs both a .png image and a .json metadata file