Skip to content

Working with Assets

Most real apps need assets — icons, images, sounds, fonts, data files. Whittl's Assets panel is where you manage them, and the AI can reference, reason about, and (optionally) generate them.

The assets folder

Every project has an assets/ folder in its root. Files dropped there are preserved across generations and accessible to your generated code.

Typical structure:

my_project/
├── main.py
├── assets/
│   ├── logo.png
│   ├── icon.ico
│   ├── ui/
│   │   ├── button_normal.png
│   │   └── button_hover.png
│   └── sounds/
│       └── click.wav

Your code references these via relative paths:

from PySide6.QtGui import QPixmap
logo = QPixmap("assets/logo.png")

Why assets/ specifically?

Whittl's AI is trained to use assets/ as the conventional folder. Using a different name (resources/, static/, images/) works but the AI might not guess it correctly when referencing files. Stick with assets/ unless you have a strong reason.

The Assets panel

Click the Assets tab in the preview panel (next to Code, Archives, Terminal, Help). The Assets panel shows every file in your project's assets/ folder, organized by type.

What you see per asset:

  • Thumbnail preview for images and videos
  • Filename
  • Size
  • AI-generated or user-provided badge (see Lock/protect)
  • Delete button

Drag any asset to the editor to insert its path into your current file.

Adding assets

Three ways:

  1. Drag-drop from your file manager into the Assets panel.
  2. Copy-paste an image from your clipboard while the Assets panel is focused.
  3. File → Import Files from the menu — opens a file picker.

Whittl copies the file to your project's assets/ folder and marks it as user-provided.

AI-generated assets (games only)

For game projects, Whittl can generate sprites, icons, backgrounds, and textures via AI image generation. This is gated behind the Asset Generation toggle in Preferences → AI Generation.

When enabled:

  • The AI analyzes your code for missing sprite references (QPixmap("assets/player.png") without the file existing)
  • Offers to generate the missing assets via an image backend (Gemini, DALL-E, or a fallback based on your config)
  • Adds the generated files to assets/ and marks them as AI-generated

This ONLY applies to game projects. For utility apps, the feature's off by default because most utility apps don't need AI art and the generation wastes tokens.

Pick an art style once

For game projects with many assets, the first time you generate something Whittl asks you to pick an art style ("Pixel art, 8-bit" / "Flat design" / "Hand-drawn watercolor" / etc.). That style gets applied to every subsequent asset so the game looks coherent.

Change styles anytime via the Assets panel's Art Style dropdown.

Lock and protect

User-provided assets (the ones you added manually) are locked by default. AI-generated assets are unlocked (AI can regenerate them). The lock protects you from the AI accidentally overwriting your logo or a hand-drawn sprite.

Changing lock state

Right-click an asset → Mark as Protected / Mark as AI-Generated.

Protected (locked) assets get a lock icon in the panel. The AI won't regenerate them even if you prompt for it — you have to unlock first.

When you'd unlock a locked asset

Typical: you dropped in a placeholder early, now you want the AI to replace it with a better version. Unlock → prompt for the new asset → lock the new version.

Reference images

Attach an image to the chat input as a reference (not asset) to guide a generation:

  • "Generate a player sprite that matches this style" + attached reference → AI generates in matching aesthetic
  • "Redesign this login screen" + attached screenshot → Screenshot to App workflow

Reference images don't end up in the project's assets/ folder — they're sent to the AI as context for the current prompt only.

The data/ folder

Distinct from assets/. data/ is for runtime data — saved user state, databases, logs — that your app writes at runtime. Whittl's AI protects data/ from overwrites even more aggressively than assets/:

  • AI won't generate or modify files in data/
  • AI won't reference files there expecting them to exist (since they're user-generated at runtime)

If your generated app needs to persist state (settings, saved games, user files), it should write to data/. See Project Folder Structure.

Using assets in built executables

When you build your project (Building an Installer), the assets/ folder is bundled into the output executable automatically. Your code continues to reference assets/file.png; the runtime extracts assets to a temp folder on launch.

Path handling in built apps

Generated code that does open("assets/file.txt") works during Test Run (the cwd is the project folder) but fails when the built .exe runs from a different cwd. Fix:

import os, sys
# Resolve relative to the executable, not cwd
if getattr(sys, 'frozen', False):
    base = sys._MEIPASS
else:
    base = os.path.dirname(os.path.abspath(__file__))

asset_path = os.path.join(base, "assets", "file.txt")
with open(asset_path) as f:
    ...

Whittl's auto-fix has rules that catch most of these, but if you hand-wrote path handling, double-check it works in the built binary.

Useful prompt patterns:

  • "Use assets/logo.png in the header, sized to 64px wide" — AI adds the image to the right place
  • "Replace the current button icon with assets/new_button.svg"
  • "The assets/click.wav should play when any button is pressed"
  • "Create a theme based on the colors in assets/reference.png" (extracts palette from reference)

The AI handles these directly — no asset-panel interaction needed.

What's next