Project Structure

Each Doodle Engine game lives in a folder containing its content, media, and application. Doodle Studio opens content files in Visual mode or Source mode. The CLI runs commands against the project folder, and a separate code editor opens the files directly.

Knowing where things are is helpful when adding files by hand, using version control, automating validation and builds, or customizing the game’s renderer.

A game project has this structure:

my-game/
  content/
    characters/       # Character YAML files
    dialogues/        # Dialogue .dlg files
    interludes/       # Interlude YAML files
    items/            # Item YAML files
    journal/          # Journal entry YAML files
    locales/          # Locale YAML files (en.yaml, es.yaml, etc.)
    locations/        # Location YAML files
    maps/             # Map YAML files
    quests/           # Quest YAML files
    game.yaml         # Game configuration
    player.yaml       # Optional player profile and stats
  assets/
    images/
      banners/        # Location and interlude banner images
      portraits/      # Character portrait images
      items/          # Item icons and detail images
      maps/           # Map background images
      ui/             # Interface images (shell screens, frames)
    audio/
      music/          # Music tracks
      sfx/            # Game sound effects and ambient sounds
      ui/             # Renderer UI sounds
      voice/          # Dialogue voice lines
    video/            # Cutscene video files
  metadata/           # Optional Studio notes
    flags-and-vars.yaml
  src/
    main.tsx          # Entry point
    App.tsx           # Root component
    project.ts        # Stable identity used to keep saves separate
    locale-options.ts # Builds the language list from the loaded locales
    renderer-scale.ts # Fits fixed-size themes to the browser window
    index.css         # Loads the theme and your custom styles
    renderer-theme.css     # Current theme styles
    renderer-overrides.css # Your custom styles
  index.html          # HTML shell
  README.md           # Commands and pointers for this project
  package.json
  tsconfig.json       # TypeScript settings your editor reads
  .gitignore

Content Directory

All game content lives in content/. The engine loads each type from its corresponding directory:

Directory	File Type	Contains
characters/	.yaml	Character definitions
dialogues/	.dlg	Dialogue scripts
interludes/	.yaml	Interlude definitions
items/	.yaml	Item definitions
journal/	.yaml	Journal entries
locales/	.yaml	Translation strings
locations/	.yaml	Location definitions
maps/	.yaml	Map definitions
quests/	.yaml	Quest definitions

Which name counts: the filename or the id?

YAML entities are identified by the id field inside the file, so tavern.yaml could be renamed without changing the game. Dialogues and locales are the exception: a dialogue’s ID is its filename without .dlg, and a locale’s code is its filename without .yaml. Renaming those files changes their IDs.

The optional player.yaml file defines the player’s profile fields and starting stats. game.yaml decides whether the built-in renderer uses those profile fields directly or asks the player to enter replacement profile text. See Characters & Party.

game.yaml

game.yaml holds the settings Doodle Engine reads when a new game begins, including its initial game state. Your First Game walks through the starter configuration. YAML Schemas lists every field the file supports.

Locale Files

Each entry in a locale file pairs a localization key with the text to display in that language. The filename sets the locale code: en.yaml becomes "en", and es.yaml becomes "es".

content/locales/en.yaml

location.tavern.name: 'The Rusty Tankard'
character.bartender.name: 'Greta'

Use the key in another content file by adding @ before it:

content/locations/tavern.yaml

id: tavern
name: '@location.tavern.name'

Assets Directory

The assets/ directory contains the images, audio, and video used by the game. Studio can import a file and copy it into the appropriate folder, or you can place files there directly:

• images/: location banners (banner field), character portraits (portrait), item icons/images, interlude images
• audio/: music tracks, ambient sounds, game sound effects, UI sounds, and voice lines
• video/: video files played by dialogue VIDEO effects or custom renderer code

Content files usually use bare filenames. The engine uses the field to find the correct folder, such as banner: tavern.png in assets/images/banners/. Shell config in game.yaml uses project-relative paths beginning with assets/.

Metadata Directory

Studio creates the optional metadata/ directory when you add notes for flags or variables. flags-and-vars.yaml stores those explanations with the project so they can be shared and versioned with the game.

Metadata describes the project but is not game content. The engine does not load this directory, and deleting a note does not remove or change its flag or variable. See Flags & Variables for editing and reviewing these notes in Studio.

Source Directory

The src/ directory contains the game application. Studio uses this application when you select Preview or Build. Edit these files to customize the renderer and the rest of the interface.

• main.tsx: mounts the React app
• App.tsx: fetches the content registry (loaded game definitions) and asset manifest (media list), then renders GameShell or your custom renderer providers
• project.ts: contains the project’s generated identity. Keep it unchanged for every release of the same game. If a copied project becomes a different game, give the copy a new ID before releasing it.
• locale-options.ts: turns the loaded locale codes into the language list shown in Settings
• renderer-scale.ts: fits the built-in renderer to the browser window when the current theme uses a fixed-size layout
• index.css: imports renderer-theme.css first and renderer-overrides.css second
• renderer-theme.css: contains the current theme and is replaced by npm run theme -- <name>
• renderer-overrides.css: contains your CSS changes and is kept when you switch themes

For custom renderers, replace GameRenderer with your own components. The useGame React hook gives those components the current game screen and player actions. See Custom Renderer.

Where to continue

If you are working in Doodle Studio, continue with the Doodle Studio overview. It opens the starter project from the first-game tutorial and introduces the editor before moving into its individual tools.

If you are working in a text editor, continue with Writing Dialogues. The CLI Commands page is available when you need the complete command reference.