Initial Guidebook Documentation

This commit is contained in:
Noah 2020-05-22 21:03:01 -07:00
parent 27896a9253
commit 82d50f1c91
20 changed files with 351 additions and 241 deletions

View File

@ -121,7 +121,8 @@ dist-free: doodads bindata build-free __dist-common
__dist-common: __dist-common:
mkdir -p dist/doodle-$(VERSION) mkdir -p dist/doodle-$(VERSION)
cp bin/* dist/doodle-$(VERSION)/ cp bin/* dist/doodle-$(VERSION)/
cp -r README.md Changes.md "Open Source Licenses.md" dist/doodle-$(VERSION)/ cp -r README.md Changes.md "Open Source Licenses.md" rtp dist/doodle-$(VERSION)/
rm -rf dist/doodle-$(VERSION)/rtp/.git
cd dist && tar -czvf doodle-$(VERSION).tar.gz doodle-$(VERSION) cd dist && tar -czvf doodle-$(VERSION).tar.gz doodle-$(VERSION)
cd dist && zip -r doodle-$(VERSION).zip doodle-$(VERSION) cd dist && zip -r doodle-$(VERSION).zip doodle-$(VERSION)

View File

@ -0,0 +1,16 @@
SHELL := /bin/bash
# `make serve` to serve the mkdocs site on localhost.
.PHONY: serve
serve:
mkdocs serve
# `make build` to build the static documentation site.
.PHONY: build
build:
mkdocs build
# `make clean` cleans everything up.
.PHONY: clean
clean:
rm -rf site

View File

@ -1,28 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>Project: Doodle Guidebook</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="pages/res/main.css">
</head>
<body>
<div id="sidebar">
<nav>
<h3>Navigation</h3>
<ul>
<li><a href="pages/Home.html" target="frame">Home</a></li>
</ul>
</nav>
</div>
<div id="content">
<div>
<iframe name="frame" src="pages/Home.html"></iframe>
</div>
</div>
</body>
</html>

View File

@ -0,0 +1,3 @@
# About Project: Doodle
Lorem ipsum.

View File

@ -0,0 +1,20 @@
# Drawing Doodads in an External Program
Doodad sprites can be drawn using any image editor and saved as .png files
(with transparency). You can then create a doodad file from your series of
PNG images.
Most of the built-in doodads that ship with the game were created in this way.
## Create a Doodad from Images
Save each frame of your doodad as a separate PNG image and then use the `doodad`
command-line tool to convert them to a `.doodad` file.
```bash
# Usage:
doodad convert [options] <inputs.png> <output.doodad>
# Example:
doodad convert door-closed.png door-open.png door.doodad
```

View File

@ -0,0 +1,27 @@
# Drawing a Doodad In-Game
Project: Doodle has some **limited** support to draw your doodad sprites
in-game. Currently you can only draw one frame (image) for the doodad
and save it to disk.
To start a new doodad, open the game and enter the level editor.
Select the "New Doodad" button at the top of the screen to start drawing a
new doodad. Choose the size (square) of its sprite when prompted.
Doodads saved in-game go in your user config directory for the game. On Linux,
this is at ~/.config/doodle.
If you want to create a doodad with multiple frames (to animate it or have
varying states that change the doodad's appearance in the level), the
`doodad` tool is recommended. See
[drawing images in an external program](edit-external.md).
## Future Planned Features
Creating doodads in-game is intended to be a fully supported feature. The
following features are planned to be supported:
* Support editing multiple frames instead of only the first frame.
* Implement some features only available on the `doodad` tool using in-game
UI, such as attaching JavaScripts to the doodad.

View File

@ -0,0 +1,43 @@
# Creating Custom Doodads
Project: Doodle is designed to be modder friendly and provides tools to help
you create your own custom doodads to use in your levels.
You can draw the sprites for the doodad either in-game or using an external
image editor. Then, you can program their logic using JavaScript to make them
"do" stuff in-game and interact with the player and other doodads.
* Drawing your Doodad's Sprites
* [In-Game](edit-in-game.md)
* [In an External Program](edit-external.md)
* Program its Behavior
* [JavaScript](scripts.md)
## doodad (Command Line Tool)
Your copy of the game should have shipped with a `doodad` command-line tool
bundled with it. On Windows it's called `doodad.exe` and should be in the same
folder as the game executable. On Mac OS, it is inside the .app bundle.
The `doodad` tool provides a command-line interface to create and inspect
doodad and level files from the game. You'll need to use this tool, at the very
least, to attach a JavaScript to your doodad to make it "do" stuff in-game.
You can create a doodad from PNG images on disk, attach or view the JavaScript
source on them, and view/edit metadata.
```bash
# (the $ represents the shell prompt in a command-line terminal)
# See metadata about a doodad file.
$ doodad show /path/to/custom.doodad
# Create a new doodad based on PNG images on disk.
$ doodad convert frame0.png frame1.png frame2.png output.doodad
# Add and view a custom script attached to the doodad.
$ doodad install-script index.js custom.doodad
$ doodad show --script custom.doodad
```
More info on the [`doodad` tool](../doodad-tool.md) here.

View File

@ -0,0 +1,99 @@
# Creating Custom Levels
One of the core gameplay features is its Level Editor which lets you draw your
own custom maps to play and share with others.
From the game's Main Menu, click on the "Create a Level" button to open the
level editor. To edit an existing custom level, click on the "Edit a Level"
button instead.
## Level Properties
When creating a new level, you first choose some settings for it. These are
described below:
### Page Type
This setting controls the size and boundaries of your level, and control the
appearance of the notebook paper background of your level.
* **Bounded** is the default. The camera won't scroll past the top-left corner
of the page (0,0), and the level size is capped to 2550x3300, or the
approximate size of an 11:9 standard sheet of notebook paper in pixels.
* **No Negative Space** is like Bounded, but the width and height of the level
have no boundary. Levels can grow "infinitely" to the right and downward
but no negative coordinates past the top or left edge.
* **Unbounded** allows for "infinite" sized maps that give unlimited room to
grow your level. The wallpaper on this level type only uses the "tiling"
pattern, so notebook-themed levels won't show the top/left decorations.
### Wallpaper
The wallpaper affects the "theme" of your level. Project: Doodle is themed around
hand-drawn mazes on paper, so the built-in themes look like various kinds of
paper.
* **Notebook** looks like standard ruled notebook paper. It's a white paper with
blue horizontal lines, a single red vertical line down the left, and a wide
margin on the top and left edges.
* **Legal Pad** looks like ruled yellow legal pad. It's similar to Notebook but
has yellow paper and a second vertical red line down the left.
* **Blueprint** is a dark blueprint paper background with a repeating grid pattern.
Notably, the default Color Palette for this theme is different than normal:
"solid" lines are white instead of black, to show up better against the dark
background.
The decorations of the wallpaper vary based on the Page Type. For example, the
Notebook and Legal Pad have extra padding on the top of the page and red lines
going down just the left side, and the rest of the level uses the repeating blue
lines pattern. The page types and their effect on the wallpapers are:
* **Bounded** and **No Negative Space** will show the decorations for the top
and left edges of the page, as these levels are bounded on their top/left
corner.
* **Unbounded** levels only use the repeating tiled pattern across the entire
level, because there is no top-left boundary to anchor those decorations to.
## Editor Mode Interface
![Level Editor View](../images/editor-1.png)
Quick 5-minute tour of what you're looking at:
* The top of the window has your **Menu Bar**:
* **New Level** opens the "Create a New Level" menu.
* **New Doodad** opens the Doodad Editor for drawing a new custom doodad.
You're prompted for the size of the doodad, which will be its width and
height boundary. For example, a size of "100" means a 100x100 pixel graphic
for your custom doodad.
* **Save** and **Save as...** let you save the current Level or Doodad you're
drawing to disk. "Save" will only ask for the filename once whereas "Save as"
asks every time.
* **Load** opens the "Edit a Level" menu to choose a Level or Doodad to edit.
* **Options** options the Level Options dialog so you can modify the page type
and wallpaper setting.
* The panel on the left side of the window is your **Tool Box**. Clicking these
buttons activates a specific drawing tool or mode:
* **Pencil Tool** lets you click, drag, and draw pixels of your selected
Palette color onto your level freehand.
* **Line Tool** lets you easily draw a straight line between two points. Click
in your level where you want the first point to be, and drag your mouse to
the second point. Release the mouse to commit the line to your drawing.
* **Rectangle Tool** lets you easily draw rectangles on your level.
* **Ellipse Tool** lets you draw circles or elliptical shapes.
* **Doodad Tool** lets you drag doodads such as buttons and doors onto your
level. See the [Doodad Tool](#doodad-tool) below.
* **Link Tool** lets you link doodads together so that they can interact off
each other. For example, a Button connected to an Electric Door will cause
the door to open and close when the button is pressed. See [Link Tool](#link-tool)
below.
* **Eraser Tool** cleans up your mistakes. Click and drag over pixels you've
drawn to delete the pixels from your level.
* **Brush Size:** the "Size:" label shows the brush size of your current drawing
tool. This translates to the line thickness, or how big your pixels are when
drawn into the level. Click the + and - buttons to increase or decrease the
brush size, and draw thicker or thinner lines.
* The panel on the right side of the window is your **Palette** of colors to
draw with.
![Doodad Toolbar View](../images/editor-2.png)

View File

@ -0,0 +1,118 @@
# Doodad Tool
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/project-doodle/doodad`.
On Mac OS, it is found 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
```bash
# Usage:
doodad show [doodad or level filename]
```
Shows metadata and details about a level or doodad file.
Examples:
```bash
$ doodad show button.doodad
===== Doodad: button.doodad =====
Headers:
File version: 1
Game version: 0.0.10-alpha
Doodad title: Button
Author: Noah
Locked: true
Hidden: false
Script size: 473 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
```
## Convert
```bash
# Usage:
doodad convert [options] <input files.png> <output file.doodad>
```
### 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.
doodad convert --tag color=blue frame{0,1,2,3}.png custom.doodad
```
### Convert a level to a PNG image
```bash
doodad convert my.level output.png
```
### Create a level from a PNG image
```bash
doodad convert level.png output.level
```

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 93 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 106 KiB

View File

@ -0,0 +1,15 @@
# Welcome to Project: Doodle
![](images/main-menu.png)
[Project: Doodle](about.md) is a drawing-based maze game themed around hand-drawn
maps on paper. You can draw a level for a 2D platformer game, drag-and-drop
"doodads" such as buttons and doors into your level, and play it.
## Table of Contents
* [Creating Custom Levels](custom-levels/)
* [Creating Custom Doodads](custom-doodads/)
* [Draw Sprites In-Game](custom-doodads/edit-in-game.md)
* [Draw Sprites with an External Program](custom-doodads/edit-external.md)
* [Program Them with JavaScript](custom-doodads/scripts.md)

View File

@ -0,0 +1,8 @@
site_name: "Project: Doodle Guidebook"
nav:
- Home: index.md
- About: about.md
- "Custom Doodads": custom-doodads/
markdown_extensions:
- toc:
permalink: "#"

View File

@ -1,9 +0,0 @@
# Guidebook to {{ app_name }}
This is the users manual to {{ app_name }}, a drawing-based maze game.
## Creating Custom Content
* [Doodad Scripts](DoodadScripts.html)
v{{ app_version }}

View File

@ -1,28 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>{{ app_name }} Guidebook</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="pages/res/main.css">
</head>
<body>
<div id="sidebar">
<nav>
<h3>Navigation</h3>
<ul>
<li><a href="pages/Home.html" target="frame">Home</a></li>
</ul>
</nav>
</div>
<div id="content">
<div>
<iframe name="frame" src="pages/Home.html"></iframe>
</div>
</div>
</body>
</html>

View File

@ -1,15 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<title>{{ title }}</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="res/markdown.css">
<link rel="stylesheet" type="text/css" href="res/syntax.css">
</head>
<body>
$CONTENT
</body>
</html>

View File

@ -1,66 +0,0 @@
body,html {
margin: 0;
padding: 0;
width: 100%;
height: 100%;
overflow: hidden;
}
body {
background-color: #EEE;
font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
font-size: 16px;
color: #000;
line-height: 1.4em;
}
div#sidebar {
position: absolute;
top: 0;
left: 0;
bottom: 0;
width: 220px;
background-color: #000066;
color: #EEE;
}
nav {
padding: 1.5rem;
}
nav ul {
margin: 0;
padding: 0;
list-style: none;
}
nav ul li {
display: block;
}
nav a:link, nav a:visited {
color: #EEE;
text-decoration: none;
}
nav a:hover, nav a:active {
color: #F9F;
text-decoration: underline;
}
div#content {
position: absolute;
top: 0;
left: 220px;
right: 0;
bottom: 0;
}
div#content div {
position: relative;
width: 100%;
height: 100%;
}
div#content iframe {
width: 100%;
height: 100%;
border: 0;
overflow: auto;
}

View File

@ -1,25 +0,0 @@
body {
background-color: #EEE;
font-family: "Trebuchet MS", Arial, Helvetica, sans-serif;
font-size: 16px;
color: #000;
line-height: 1.4em;
margin: 2rem;
}
a:link, a:visited {
color: #006699;
text-decoration: underline;
}
a:hover, a:active {
color: #996600;
}
.codehilite {
border: 1px solid #222;
}
pre {
font-family: "Lucida Console", "DejaVu LGC Sans Mono", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Ubuntu Mono", monospace;
margin: 0;
padding: 8px;
}

View File

@ -1,69 +0,0 @@
.codehilite .hll { background-color: #ffffcc }
.codehilite { background: #f8f8f8; }
.codehilite .c { color: #408080; font-style: italic } /* Comment */
.codehilite .err { border: 1px solid #FF0000 } /* Error */
.codehilite .k { color: #008000; font-weight: bold } /* Keyword */
.codehilite .o { color: #666666 } /* Operator */
.codehilite .ch { color: #408080; font-style: italic } /* Comment.Hashbang */
.codehilite .cm { color: #408080; font-style: italic } /* Comment.Multiline */
.codehilite .cp { color: #BC7A00 } /* Comment.Preproc */
.codehilite .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */
.codehilite .c1 { color: #408080; font-style: italic } /* Comment.Single */
.codehilite .cs { color: #408080; font-style: italic } /* Comment.Special */
.codehilite .gd { color: #A00000 } /* Generic.Deleted */
.codehilite .ge { font-style: italic } /* Generic.Emph */
.codehilite .gr { color: #FF0000 } /* Generic.Error */
.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.codehilite .gi { color: #00A000 } /* Generic.Inserted */
.codehilite .go { color: #888888 } /* Generic.Output */
.codehilite .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.codehilite .gs { font-weight: bold } /* Generic.Strong */
.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.codehilite .gt { color: #0044DD } /* Generic.Traceback */
.codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
.codehilite .kp { color: #008000 } /* Keyword.Pseudo */
.codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.codehilite .kt { color: #B00040 } /* Keyword.Type */
.codehilite .m { color: #666666 } /* Literal.Number */
.codehilite .s { color: #BA2121 } /* Literal.String */
.codehilite .na { color: #7D9029 } /* Name.Attribute */
.codehilite .nb { color: #008000 } /* Name.Builtin */
.codehilite .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.codehilite .no { color: #880000 } /* Name.Constant */
.codehilite .nd { color: #AA22FF } /* Name.Decorator */
.codehilite .ni { color: #999999; font-weight: bold } /* Name.Entity */
.codehilite .ne { color: #D2413A; font-weight: bold } /* Name.Exception */
.codehilite .nf { color: #0000FF } /* Name.Function */
.codehilite .nl { color: #A0A000 } /* Name.Label */
.codehilite .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.codehilite .nt { color: #008000; font-weight: bold } /* Name.Tag */
.codehilite .nv { color: #19177C } /* Name.Variable */
.codehilite .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.codehilite .w { color: #bbbbbb } /* Text.Whitespace */
.codehilite .mb { color: #666666 } /* Literal.Number.Bin */
.codehilite .mf { color: #666666 } /* Literal.Number.Float */
.codehilite .mh { color: #666666 } /* Literal.Number.Hex */
.codehilite .mi { color: #666666 } /* Literal.Number.Integer */
.codehilite .mo { color: #666666 } /* Literal.Number.Oct */
.codehilite .sa { color: #BA2121 } /* Literal.String.Affix */
.codehilite .sb { color: #BA2121 } /* Literal.String.Backtick */
.codehilite .sc { color: #BA2121 } /* Literal.String.Char */
.codehilite .dl { color: #BA2121 } /* Literal.String.Delimiter */
.codehilite .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.codehilite .s2 { color: #BA2121 } /* Literal.String.Double */
.codehilite .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */
.codehilite .sh { color: #BA2121 } /* Literal.String.Heredoc */
.codehilite .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */
.codehilite .sx { color: #008000 } /* Literal.String.Other */
.codehilite .sr { color: #BB6688 } /* Literal.String.Regex */
.codehilite .s1 { color: #BA2121 } /* Literal.String.Single */
.codehilite .ss { color: #19177C } /* Literal.String.Symbol */
.codehilite .bp { color: #008000 } /* Name.Builtin.Pseudo */
.codehilite .fm { color: #0000FF } /* Name.Function.Magic */
.codehilite .vc { color: #19177C } /* Name.Variable.Class */
.codehilite .vg { color: #19177C } /* Name.Variable.Global */
.codehilite .vi { color: #19177C } /* Name.Variable.Instance */
.codehilite .vm { color: #19177C } /* Name.Variable.Magic */
.codehilite .il { color: #666666 } /* Literal.Number.Integer.Long */