SketchyMaze/doodle
SketchyMaze/doodle
1
0
Fork 0
Code Issues 41 Pull Requests 1 Releases Wiki Activity

Update doodad tool documentation

Browse Source
This commit is contained in:
Noah 2024-05-24 21:05:54 -07:00
parent 57b757a378
commit 90414609a9
2 changed files with 254 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

262
cmd/doodad/README.md
View File

@ -1,21 +1,116 @@
# doodad.exe # doodad.exe
The doodad tool is a command line interface for interacting with Levels and The `doodad` tool is a command line interface for interacting with Levels and Doodad files, collectively referred to as "Doodle drawings" or just "drawings" for short. It provides many useful features for custom content creators that are not available in the game's user interface.
Doodad files, collectively referred to as "Doodle drawings" or just "drawings"
for short.
# Commands - [doodad.exe](#doodadexe)
- [Quick Start](#quick-start)
- [Creating a custom doodad](#creating-a-custom-doodad)
- [Creating a custom Level Pack](#creating-a-custom-level-pack)
- [Usage](#usage)
- [Features in Depth](#features-in-depth)
- [$ `doodad convert`: to and from image files](#-doodad-convert-to-and-from-image-files)
- [$ `doodad show`: Get information about a level or doodad](#-doodad-show-get-information-about-a-level-or-doodad)
- [Editing Level or Doodad Properties](#editing-level-or-doodad-properties)
- [Where to Find It](#where-to-find-it)
## doodad convert # Quick Start
Convert between standard image files (bitmap or PNG) and Doodle drawings ## Creating a custom doodad
(levels or doodads).
This command can be used to "export" a Doodle drawing as a PNG (when run against This is an example how to fully create a custom doodad using PNG images for their sprites. The game's built-in doodads are all built in this way:
a Level file, it may export a massive PNG image containing the entire level).
It may also "import" a new Doodle drawing from an image on disk.
Example: ```bash
# Create the initial doodad from PNG images making up its layers.
% doodad convert --title "Bird (red)" --author "Myself" \
left-1.png left-2.png right-1.png right-2.png \
bird-red.doodad
# Attach my custom JavaScript to program the doodad.
% doodad install-script bird.js bird-red.doodad
# Note: `doodad show --script` can get the script back out.
# Set tags and options on my doodad
% doodad edit-doodad --tag "category=creatures" \
--tag "color=blue" \
--option "No A.I.=bool" \
bird-red.doodad
# See the Guidebook for more information!
```
## Creating a custom Level Pack
The doodad tool is currently the best way to create a custom Level Pack for the game. Level Packs will appear in the Story Mode selector, and you can install local levelpacks by putting them in that folder of your Profile Directory.
```bash
# First Quest
doodad levelpack create -t "First Quest" -d "The first story mode campaign." \
-a "$AUTHOR" --doodads none --free 1 \
"levelpacks/builtin-100-FirstQuest.levelpack" \
"levels/Castle.level" \
"levels/Boat.level" \
"levels/Jungle.level" \
"levels/Thief 1.level" \
"levels/Desert-1of2.level" \
"levels/Desert-2of2.level" \
"levels/Shapeshifter.level"
```
Some useful options you can set on your levelpack:
* Title: defaults to your first level's title.
* Description: for the Story Mode picker.
* Free levels: if you want progressive unlocking of levels, specify how many levels are unlocked to start with (at least 1). Otherwise all levels are unlocked.
* Doodads: by default any custom doodad will be bundled with the levelpack.
* Options for `--doodads` are `none`, `custom` (default), and `all`
* Use `none` if your levelpack uses _only_ built-in doodads.
# Usage
See `doodad --help` for documentation of the available commands and their options; a recent example of which is included here.
```
NAME:
doodad - command line interface for Doodle
USAGE:
doodad [global options] command [command options]
VERSION:
v0.14.1 (open source) build N/A. Built on 2024-05-24T19:23:33-07:00
COMMANDS:
convert convert between images and Doodle drawing files
edit-doodad update metadata for a Doodad file
edit-level update metadata for a Level file
install-script install the JavaScript source to a doodad
levelpack create and manage .levelpack archives
resave load and re-save a level or doodad file to migrate to newer file format versions
show show information about a level or doodad file
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--debug enable debug level logging (default: false)
--help, -h show help
--version, -v print the version
```
The `--help` or `-h` flag can be given to subcommands too, which often have their own commands and flags. For example, `doodad convert -h`
# Features in Depth
## $ `doodad convert`: to and from image files
This command can convert between image files (BMP or PNG) and Doodle drawings (levels and doodads) in both directions.
For custom doodad authors this means you can draw your sprites in a much more capable image editing tool, and create a doodad from PNG images. The game's built-in doodads are all created in this way.
This command can also be used to "export" a drawing as a PNG image: when run against a Level file, it may export a massive PNG image containing the entire level! Basically the "Giant Screenshot" function from the level editor.
It can also create a Level from a screenshot, generating the Palette from the distinct colors found (for you to assign properties to in the editor, for e.g. solid geometry).
Examples:
```bash ```bash
# Export a full screenshot of your level # Export a full screenshot of your level
@ -24,20 +119,149 @@ $ doodad convert mymap.level screenshot.png
# Create a new level based from a PNG image. # Create a new level based from a PNG image.
$ doodad convert scanned-drawing.png new-level.level $ doodad convert scanned-drawing.png new-level.level
# Create a doodad from a series of PNG images as its layers.
$ doodad convert -t "My Button" up.png down.png my-button.doodad
# Create a new doodad based from a BMP image, and in this image the chroma # Create a new doodad based from a BMP image, and in this image the chroma
# color (transparent) is #FF00FF instead of white as default. # color (transparent) is #FF00FF instead of white as default.
$ doodad convert --key '#FF00FF' button.png button.doodad $ doodad convert --key '#FF00FF' button.png button.doodad
``` ```
Supported image types: Supported image types to convert to or from:
* PNG (8-bit or 24-bit, with transparent pixels or chroma key) * PNG (8-bit or 24-bit, with transparent pixels or chroma)
* BMP (bitmap image with chroma key) * BMP (bitmap image with chroma key)
The chrome key defaults to white (`#FFFFFF`), so pixels of that color are The chrome key defaults to white (`#FFFFFF`), so pixels of that color are treated as transparent and ignored. For PNG images, if a pixel is fully transparent (alpha channel 0%) it will also be skipped. So the easiest format to use are PNG images with transparent pixels.
treated as transparent and ignored. For PNG images, if a pixel is fully
transparent (alpha channel 0%) it will also be skipped.
When converting an image into a drawing, the unique colors identified in the When converting an image into a Level or Doodad, the unique colors identified in the drawing are extracted to create the **Palette**. You will need to later edit the palette to assign meaning to the colors (giving them names or level properties). In particular, when importing a Level you'd want to mark which colors are solid ground.
drawing are extracted into the palette. You will need to later edit the palette
to assign meaning to the colors. ## $ `doodad show`: Get information about a level or doodad
The `doodad show` command can return metadata and debug the contents of a Level or Doodad file.
```
% doodad show Example.level
===== Level: Example.level =====
Headers:
File format: zipfile
File version: 1
Game version: 0.14.0
Level UUID: d136fef3-1a3a-453c-b616-05aca8dd6840
Level title: Lesson 1: Controls
Author: Noah P
Password:
Locked: false
Game Rules:
Difficulty: Normal (0)
Survival: false
Palette:
- Swatch name: solid
Attributes: solid
Color: #777777
- Swatch name: decoration
Attributes: none
Color: #ff66ff
- Swatch name: fire
Attributes: fire,water
Color: #ff0000
- Swatch name: semisolid
Attributes: semi-solid
Color: #cccccc
Level Settings:
Page type: Bounded
Max size: 2550x3300
Wallpaper: notebook.png
Attached Files:
assets/screenshots/large.png: 63377 bytes
assets/screenshots/medium.png: 25807 bytes
assets/screenshots/small.png: 6837 bytes
assets/screenshots/tiny.png: 7414 bytes
Actors:
Level contains 16 actors
Use -actors or -verbose to serialize Actors
Chunks:
Pixels Per Chunk: 128^2
Number Generated: 102
Coordinate Range: (0,0) ... (1919,2047)
World Dimensions: 1919x2047
Use -chunks or -verbose to serialize Chunks
```
Or for a doodad:
```
% doodad show example.doodad
===== Doodad: example.doodad =====
Headers:
File format: zipfile
File version: 1
Game version: 0.14.1
Doodad title: Fire Region
Author: Noah
Dimensions: Rect<0,0,128,128>
Hitbox: Rect<0,0,128,128>
Locked: true
Hidden: false
Script size: 378 bytes
Tags:
category: technical
Options:
str name = fire
Palette:
- Swatch name: Color<#8a2b2b+ff>
Attributes: solid
Color: #8a2b2b
Layer 0: fire-128
Chunks:
Pixels Per Chunk: 128^2
Number Generated: 1
Coordinate Range: (0,0) ... (127,127)
World Dimensions: 127x127
Use -chunks or -verbose to serialize Chunks
```
## Editing Level or Doodad Properties
The `edit-doodad` and `edit-level` subcommands allow setting properties on your custom files programmatically.
Properties you can set for both file types include:
* Metadata like the Title and Author name
* Lock your drawing from being edited in-game
For Doodads, you can set their Tags and Options, Hitbox, etc. - most of the useful settings are supported, as the game's built-in doodads use this program!
# Where to Find It
The `doodad` tool ships with the official releases of the game, and may be found in one of the following places:
* **Windows:** doodad.exe should be in the same place as sketchymaze.exe (e.g. in the ZIP file)
* **Mac OS:** it is available inside the "Sketchy Maze.app" bundle, in the "Contents/MacOS" folder next to the `sketchymaze` binary.
Invoke it from a terminal like:
```bash
alias doodad="/Applications/Sketchy Maze.app/Contents/MacOS/doodad"
doodad -h
```
* **Linux:** the doodad binary should be in the same place as the sketchymaze program itself:
* In the .tar.gz file
* In /opt/sketchymaze if installed by an .rpm or .deb package
* AppImage: `./SketchyMaze.AppImage doodad` will invoke the doodad command.
* Flatpak: `flatpak run com.sketchymaze.Doodle doodad` will invoke the doodad command. Invoke it from a terminal like:
```bash
alias doodad="flatpak run com.sketchymaze.Doodle doodad"
doodad -h
```

15
cmd/doodad/commands/show.go
View File

@ -185,7 +185,7 @@ func showLevel(c *cli.Context, filename string) error {
} }
// Serialize chunk information. // Serialize chunk information.
showChunker(c, lvl.Chunker) showChunker(c, lvl.Chunker, 0)
fmt.Println("") fmt.Println("")
return nil return nil
@ -251,7 +251,7 @@ func showDoodad(c *cli.Context, filename string) error {
for i, layer := range dd.Layers { for i, layer := range dd.Layers {
fmt.Printf("Layer %d: %s\n", i, layer.Name) fmt.Printf("Layer %d: %s\n", i, layer.Name)
showChunker(c, layer.Chunker) showChunker(c, layer.Chunker, i)
} }
fmt.Println("") fmt.Println("")
@ -268,7 +268,7 @@ func showPalette(pal *level.Palette) {
fmt.Println("") fmt.Println("")
} }
func showChunker(c *cli.Context, ch *level.Chunker) { func showChunker(c *cli.Context, ch *level.Chunker, layer int) {
var ( var (
worldSize = ch.WorldSize() worldSize = ch.WorldSize()
chunkSize = int(ch.Size) chunkSize = int(ch.Size)
@ -279,9 +279,16 @@ func showChunker(c *cli.Context, ch *level.Chunker) {
visualize = c.Bool("visualize-rle") visualize = c.Bool("visualize-rle")
specificChunk = c.String("chunk") specificChunk = c.String("chunk")
) )
// If it's a Zipfile, count its chunks.
var chunkCount = len(ch.Chunks)
if ch.Zipfile != nil {
chunkCount = len(level.ChunksInZipfile(ch.Zipfile, layer))
}
fmt.Println("Chunks:") fmt.Println("Chunks:")
fmt.Printf(" Pixels Per Chunk: %d^2\n", ch.Size) fmt.Printf(" Pixels Per Chunk: %d^2\n", ch.Size)
fmt.Printf(" Number Generated: %d\n", len(ch.Chunks)) fmt.Printf(" Number Generated: %d\n", chunkCount)
fmt.Printf(" Coordinate Range: (%d,%d) ... (%d,%d)\n", fmt.Printf(" Coordinate Range: (%d,%d) ... (%d,%d)\n",
worldSize.X, worldSize.X,
worldSize.Y, worldSize.Y,