# Doodad Program

The game ships with a command-line program called `doodad` which assists in creating and managing custom doodads and levels.

The `doodad` tool can show and set details on .doodad and .level files used by the game, create new doodads from PNG images and attach custom JavaScript source to program behavior of doodads.

## Where to Find It

The `doodad` tool should be in the same place as the game executable.

On Windows, the program is called `doodad.exe` and comes in the zip file next to the game executable, `doodle.exe`.

On Linux, it will typically be at `/opt/sketchymaze/doodad` if you installed the game from a .rpm or .deb package, or else for Flatpak it's included within the app bundle and invoked like so:

    $ flatpak run com.sketchymaze.Doodle doodad --help

On Mac OS, it is found inside the .app bundle; right-click the 'Sketchy Maze.app' to find the option to browse inside the .app bundle.

## Usage

Run `doodad --help` to get usage information.

The program includes several sub-commands, such as `doodad convert`. Type a subcommand and `--help` to get help on that command, for example:

    doodad convert --help

## Examples

Here are some common scenarios and use cases for the doodad tool.

### Show Level or Doodad Information

Shows metadata and details about a level or doodad file.

    # Usage:
    doodad show [doodad or level filename]

Examples:

    ### About a doodad file
    $ doodad show button.doodad
    ===== Doodad: button.doodad =====
    Headers:
      File version: 1
      Game version: 0.7.0
      Doodad title: Button
            Author: Noah
            Locked: true
            Hidden: false
       Script size: 922 bytes

    Palette:
      - Swatch name: Color<#000000+ff>
        Attributes:  solid
        Color:       #000000
      - Swatch name: Color<#666666+ff>
        Attributes:  none
        Color:       #666666
      - Swatch name: Color<#999999+ff>
        Attributes:  fire
        Color:       #999999

    Layer 0: button1
    Chunks:
      Pixels Per Chunk: 37^2
      Number Generated: 1
      Coordinate Range: (0,0) ... (36,36)
      World Dimensions: 36x36
      Use -chunks or -verbose to serialize Chunks

    Layer 1: button2
    Chunks:
      Pixels Per Chunk: 37^2
      Number Generated: 1
      Coordinate Range: (0,0) ... (36,36)
      World Dimensions: 36x36
      Use -chunks or -verbose to serialize Chunks

    ### About a level file
    $ doodad show 'Tutorial 2.level'
    ===== Level: Tutorial 2.level =====
    Headers:
      File version: 1
      Game version: 0.7.0
       Level title: Lesson 2: Keys & Doors
            Author: Noah P
          Password:
            Locked: false

    Palette:
      - Swatch name: rock
        Attributes:  solid
        Color:       #996600
      - Swatch name: grass
        Attributes:  solid
        Color:       #00ff00
      - Swatch name: stone
        Attributes:  solid
        Color:       #888888
      - Swatch name: water
        Attributes:  water
        Color:       #0099ff
      - Swatch name: spikes
        Attributes:  fire
        Color:       #ff0000
      - Swatch name: hot lava
        Attributes:  fire
        Color:       #ff3300

    Level Settings:
      Page type: Bounded
       Max size: 2550x3300
      Wallpaper: legal.png

    Attached Files:
      None

    Actors:
      Level contains 35 actors
      Use -actors or -verbose to serialize Actors

    Chunks:
      Pixels Per Chunk: 128^2
      Number Generated: 206
      Coordinate Range: (-128,0) ... (2559,3327)
      World Dimensions: 2687x3327
      Use -chunks or -verbose to serialize Chunks

### Attach and Export Doodad Scripts

Doodads are programmed in JavaScript and the script can be attached and read using the doodad program.

Usage:

    # Set the doodad script from filename.js
    doodad install-script filename.js custom.doodad

    # View the script from a doodad file
    doodad show --script custom.doodad

Example:

    $ doodad show --script key-blue.doodad
    // key-blue.doodad.js
    function main() {
        var color = Self.GetTag("color");
        var quantity = color === "small" ? 1 : 0;

        Events.OnCollide(function(e) {
            if (e.Settled) {
                Sound.Play("item-get.wav")
                e.Actor.AddItem(Self.Filename, quantity);
                Self.Destroy();
            }
        })
    }

### Edit Level or Doodad Properties

The `doodad edit-level` and `doodad edit-doodad` commands can set certain properties on these types of drawings.

Example:

    $ doodad edit-level --title "My First Level" example.level

Available properties that can be modified are as follows:

- edit-doodad
  - `--title value`: set the doodad's title (display name).
  - `--author value`: set the author's name (default is your OS username).
  - `--tag value, -t value`: set a custom tag (key=value format) on your doodad.
  - `--hide, --unhide`: edit the Hidden attribute on a doodad. Hidden doodads don't appear in the Doodad Dropper window of the level editor.
  - `--lock, --unlock`: edit the Locked attribute on a doodad. Locked doodads can not be opened for editing in-game.
- edit-level
  - `--title value`: set the level's title.
  - `--author value`: set the author's name (default is your OS username).
  - `--password value`: set the password for the level (not currently used).
  - `--type value`: set the page type, one of: Bounded, Unbounded, NoNegativeSpace, Bordered.
    - Note: Bordered is not yet implemented, and behaves the same as Bounded.
  - `--max-size WxH`: set the page size for Bounded levels, like 2550x3300.
  - `--wallpaper name.png`: set the wallpaper image filename.
  - `--lock, --unlock`: edit the Locked attribute on a level. Locked levels can not be opened for editing in-game.

### Convert To/From Images

The `doodad convert` command can turn PNG or BMP images into doodads or level files, and vice versa!

    # Usage:
    doodad convert [options] <input files.png> <output file.doodad>

Only PNG or bitmap images are supported.

#### Creating a Doodad from PNG images

Suppose you have PNG images named "frame0.png" through "frame3.png" and want to create a doodad from those images. This will convert them to the doodad file "custom.doodad":

    # Convert PNG images into a doodad.
    doodad convert frame0.png frame1.png frame2.png frame3.png custom.doodad

    # The same, but also attach custom tags with the doodad.
    # The doodad script can check its tags and you can have one
    # common script for multiple variations of a doodad, e.g.,
    # all four of the built-in Colored Locked Doors share a script.
    doodad convert --tag color=blue frame{0,1,2,3}.png custom.doodad

    # Convert the doodad back into an image.
    # NOTE: only the 1st frame (frame0) can be exported, currently.
    doodad convert custom.doodad frame0.png

The order of the given PNG images will be the order of the doodad layers created; the first image will be Layer 0, the second Layer 1, and so on. The names of the image files will be the names of those layers, minus the .png or .bmp file extension.

#### Creating a Level from a PNG image

A level file can be created from a PNG image:

    # Usage:
    doodad convert [options] input.png output.level

    # Set which color is 'transparent' (to show the level wallpaper behind)
    doodad convert --key '#ffffff' input.png output.level

Some considerations about this feature:

- The Palette will be created from each distinct color value found in the original PNG image. The names of each color will be named after their hex color value, and no attributes are applied by default. You will need to edit the level palette to mark colors as solid, fire, water, etc.
- The `--key` option (default #ffffff, white) sets the background color; pixels of this color in the input PNG will be 'transparent' in the level data, showing the wallpaper image behind.

#### Convert a level to a PNG image

You can also convert a .level file into a PNG (or bitmap) image, creating a sort of "large screenshot" encompassing the entire level geometry.

    # Usage:
    doodad convert my.level output.png

Some considerations about this feature:

- Doodads are not included in the output image; only the level geometry itself is.
- Brush Patterns are not applied in the output image; each color swatch in your level will represent as solid pixel colors in the output image.

The image created by this command could be fed back in to re-create the level from that image, albeit with lots of information lost in the process, such as the names and properties of Palette swatches and all the doodad placements.

« Previous Next »