340 lines
9.5 KiB
Markdown
340 lines
9.5 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.
|
|
* `--remove-actor <name or id>`: remove an actor from your level by its name
|
|
or its UUID. For example: `--remove-actor trapdoor.doodad` removes every
|
|
instance of trapdoor.doodad from the level geometry.
|
|
|
|
---
|
|
|
|
### Remove actors from your level
|
|
|
|
In case you inherit a level that needs custom doodads that you don't have, you'll
|
|
get errors in the level editor about the missing doodads. One way to remedy this
|
|
is to delete the offending doodads from the map, but you can't do this in the
|
|
editor because the doodads don't have a sprite in your map.
|
|
|
|
First, use the `doodad show --actors example.level` command and look for the
|
|
Actors segment of the result, e.g.:
|
|
|
|
```bash
|
|
$ doodad show --actors example.level
|
|
...
|
|
Actors:
|
|
Level contains 16 actors
|
|
List of Actors:
|
|
- Name: key-blue.doodad
|
|
UUID: 15f09c12-5d00-4654-9725-8e1ba10004d7
|
|
At: 362,1348
|
|
- Name: trapdoor-down.doodad
|
|
UUID: 24f85095-d13c-42e2-9156-01cb4b84723c
|
|
At: 897,398
|
|
- Name: crumbly-floor.doodad
|
|
UUID: 9ba40fc2-acc7-4e6d-821a-f0248c2ad7e1
|
|
At: 1243,1742
|
|
...
|
|
```
|
|
|
|
You can then delete these actors by either their Name (filename) or their UUID
|
|
value. Deleting by name means that all instances of that doodad will be removed
|
|
from the map.
|
|
|
|
```bash
|
|
$ doodad edit-level --remove-actor crumbly-floor.doodad example.level
|
|
```
|
|
|
|
---
|
|
|
|
### 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.
|