guidebook/docs/doodad-tool.md

299 lines
8.2 KiB
Markdown

# 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:
```bash
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.
```bash
# Usage:
doodad show [doodad or level filename]
```
Examples:
```bash
### 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](custom-doodads/scripts.md) and the
script can be attached and read using the doodad program.
Usage:
```bash
# 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:
```javascript
$ 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:
```bash
$ 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!
```bash
# 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":
```bash
# 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:
```bash
# 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.
```bash
# 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.