Update Guidebook for v0.6.0

docs/changes.md

@@ -1,5 +1,39 @@
 # Changes
 
+## v0.6.0-alpha (June 6 2021)
+
+This release brings less jank and some new features.
+
+The new features:
+
+* **Choice of Default Palette for New Levels:** when creating a new level, a
+  "Palette:" option appears which allows you to set the default colors to start
+  your level with. The options include:
+    * Default: the classic default 4 colors (black, grey, red, blue).
+    * Colored Pencil: a set with more earthy tones for outdoorsy levels
+      (grass, dirt, stone, fire, water)
+    * Blueprint: the classic Blueprint wallpaper theme, a bright version of Default
+      for dark level backgrounds.
+* **Custom Wallpapers:** unhappy with the default, paper-themed level background
+  images? You can now use your own! They attach to your level data for easy
+  transport when sharing your level with others.
+* **More Wallpapers:** a couple of new default wallpapers are added: Graph paper
+  and Dotted paper. They are both on light white paper and offer a light
+  alternative to Blueprint.
+
+Some bugs fixed:
+
+* **Collision fixes:** you should be able to walk up gentle slopes to the left
+  without jumping, as easily as you could to the right.
+* **Debugging:** the F4 key to show collision hitboxes around all doodads in
+  Play Mode now functions again, and draws boxes around _all_ doodads, not just the
+  player character.
+* **Hitboxes are tighter:** a doodad's declared hitbox size (from their JavaScript)
+  is used when a doodad collides against level geometry or other doodads. Meaning:
+  Boy, who has a narrow body but a square sprite size, now collides closer with
+  objects on his right side.
+* **Physics are tweaked:** Boy now moves and accelerates slightly faster.
+
 ## v0.5.0-alpha (Mar 31 2021)
 
 Project: Doodle is renamed to Sketchy Maze in this release.

docs/custom-levels/custom-wallpaper.md

@@ -0,0 +1,153 @@
+# Custom Wallpaper
+
+![Custom wallpaper](../images/custom-wallpaper.png)
+
+Sketchy Maze v0.6.0 introduces the ability to use your own custom wallpaper
+image to go behind your level.
+
+You may use any common image type (PNG, JPEG, or GIF) as a wallpaper image and
+it will be tiled across your level following the game's rules. For best results,
+a wallpaper image should be crafted according to the guidelines on this page.
+
+## How Wallpapers Work
+
+Any (reasonably) sized image will work as a wallpaper, depending on the
+resolution you need. The image does not need to be square. The game will
+divide your wallpaper image into four quadrants:
+
+![Illustration of a wallpaper image divided into four quadrants](../images/wallpaper-template.png)
+
+The above image is the game's default Notebook wallpaper with the four quadrants
+of the image highlighted. The game will slice your wallpaper into four equal
+quarters and tile them depending on a level's Page Type. Rectangular wallpapers
+work fine too, just the quadrants will also be rectangular.
+
+The bottom-right quadrant (**Tiled Main**) is the main repeating background image
+that covers the entire level. Unbounded levels will use _only_ this part of the
+wallpaper.
+
+Levels that have a top-left corner (Bounded and No Negative Space) will draw
+from the other three quadrants when decorating these edges of the level:
+
+* **Top Left:** the top-left corner of the page; drawn exactly one time per
+  level, where it is anchored to the top-left (0,0) coordinate of the level.
+* **Tiled Top:** the top margin of the page; tiled horizontally across the entire
+  top edge of the level.
+* **Tiled Left:** the left margin of the page; tiled vertically across the entire
+  left edge of the level.
+
+## Making a Simple Tiled Wallpaper
+
+If you already have a tiled pattern you want to use as a wallpaper, and want
+the simplest way to use that pattern with Sketchy Maze, the quick steps are:
+
+1. Suppose your original texture is 64x64 pixels and it tiles in all directions.
+2. Create a new image twice the size of the original (128x128 pixels), and
+   copy/paste your texture into it 4 times. So you now have a 128x128 version of
+   your original 64x64 and it tiles all the same.
+3. Pick your new 128x128 texture in Sketchy Maze.
+
+If you have ImageMagick handy at the command line, this command would do this
+up-tiling work:
+
+```bash
+# where clouds.jpg was a 512x512 pixel repeating texture,
+# create a twice-size image tiled from the original, now
+# you have a 1024x1024 up-tiled version of the original.
+convert -size 1024x1024 tile:clouds.jpg clouds-2x.jpg
+```
+
+## Example Wallpapers
+
+Here are a couple of examples you can use. Right-click and save these images
+and then select them as your custom wallpaper in Sketchy Maze:
+
+### Blue Notebook
+
+![Blue Notebook](../images/blue-notebook.png)
+
+A light blue version of the default Notebook paper.
+
+### Clouds
+
+![Clouds](../images/clouds.png)
+
+The wallpaper used in the screenshot at the top of this page. Full-color
+JPEG quality photos work fine as wallpapers. This image was created via the
+[Making a Simple Tiled Wallpaper](#making-a-simple-tiled-wallpaper) process
+detailed above.
+
+## Extracting Wallpapers
+
+Getting a wallpaper back _out_ of a level is not currently an easy task, but
+it can be done using the [`doodad` tool](../doodad-tool.md) on the command line
+to inspect your level file.
+
+Your custom levels are saved in your [profile directory](../profile-directory.md),
+so point the `doodad` command at your files therein. The `doodad show` command
+will show if a level has any attached files, such as wallpaper images:
+
+```bash
+$ doodad show example.level
+===== Level: example.level =====
+Headers:
+  File version: 1
+  Game version: 0.6.0-alpha
+   Level title: Alpha
+        Author: kirsle
+      Password:
+        Locked: false
+
+Palette:
+  - Swatch name: solid
+    Attributes:  solid
+    Color:       #000000
+  - Swatch name: decoration
+    Attributes:  none
+    Color:       #999999
+  - Swatch name: fire
+    Attributes:  fire
+    Color:       #ff0000
+  - Swatch name: water
+    Attributes:  water
+    Color:       #0000ff
+
+Level Settings:
+  Page type: Bounded
+   Max size: 2550x3300
+  Wallpaper: custom.b64img
+
+Attached Files:
+  assets/wallpapers/custom.b64img: 1156 bytes
+
+Actors:
+  Level contains 0 actors
+  Use -actors or -verbose to serialize Actors
+
+Chunks:
+  Pixels Per Chunk: 128^2
+  Number Generated: 0
+  Coordinate Range: (0,0) ... (127,127)
+  World Dimensions: 127x127
+  Use -chunks or -verbose to serialize Chunks
+```
+
+The "Attached Files:" section shows the names and sizes of any files embedded
+in the level, or "None" if none.
+
+You can get the data of an attached file with `doodad show --attachment=<file>`:
+
+```bash
+$ doodad show --attachment=assets/wallpapers/custom.b64img example.level
+```
+
+The image is encoded in Base64 so the above command would spit out a bunch
+of random numbers and letters. If you pipe it into a base64 decoder you can
+save it as an image file:
+
+```bash
+# (the -a is a shortcut for --attachment)
+$ doodad show -a assets/wallpapers/custom.b64img example.level | base64 -d > out.png
+```
+
+Future releases of the game may make this process easier.

docs/custom-levels/index.md

@@ -33,6 +33,8 @@ You can change these settings later if you change your mind.
 
 ### Wallpaper
 
+![Wallpaper options on New Level](../images/palettes.png)
+
 The wallpaper affects the "theme" of your level. Sketchy Maze is themed around
 hand-drawn mazes on paper, so the built-in themes look like various kinds of
 paper.
@@ -42,10 +44,19 @@ paper.
   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.
+* **Graph paper** `new in v0.6.0` is a white paper with a repeating grid pattern
+  of light-grey lines about 32px each; a darker dotted gray grid every 3x3 units;
+  and a teal grid every 6x6 units. A light version of Blueprint.
+* **Dotted paper** `new in v0.6.0` is a white page with a repeating pattern of
+  single dots every 32 pixels apart. Most dots are light blue but with a grid of
+  red dots every 6x6 units. It has the same grid spacing as the Graph paper.
 * **Blueprint** is a dark blueprint paper background with a repeating grid pattern.
-  Notably, the default Color Palette for this theme is different than normal:
+  A dark version of Graph paper; you'll want to pair it with the **Blueprint Palette**
-  "solid" lines are white instead of black, to show up better against the dark
+  which has light colors for level geometry by default.
-  background.
+* **Pure White** is a blank, white (#FFFFFE) background color with nothing going
+  on except for what you draw on your level.
+* **Custom wallpaper...** lets you use your own wallpaper image. See
+  [Custom Wallpaper](custom-wallpaper.md).
 
 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
@@ -58,6 +69,39 @@ lines pattern. The page types and their effect on the wallpapers are:
 * **Unbounded** levels only use the repeating tiled pattern across the entire
   level, because there is no top-left boundary to anchor those decorations to.
 
+### Default Palette
+
+When starting a **new** level, you may choose a default Palette to start out
+with. The available options as of **version 0.6.0** are:
+
+* **Default:** the classic palette from previous alpha game releases.
+    1. **solid**: black, solid geometry
+    2. **decoration**: light grey
+    3. **fire**: red, fire
+    4. **water**: blue, water
+* **Colored Pencil:** a new palette with some more varied default colors.
+    1. **grass**: green, solid geometry
+    2. **dirt**: brown, solid
+    3. **stone**: dark grey, solid
+    4. **fire**: red, fire
+    5. **water**: light blue (#0099FF), water
+* **Blueprint:** the classic palette for levels with the Blueprint wallpaper:
+    1. **solid**: white, solid
+    2. **decoration:** light grey
+    3. **fire**: light red (#FF5000), fire
+    4. **water**: light blue (#0099FF), water
+    5. **electric**: yellow, solid
+
+In earlier alpha versions of the game, the Blueprint palette was chosen by
+default when the level starts out with the Blueprint wallpaper, which has a
+very dark background color and Blueprint was basically a bright version of
+the Default palette. As of v0.6.0, the user can select the palette separately
+from the wallpaper.
+
+If you're using the Blueprint wallpaper, pick the Colored Pencil or Blueprint
+palettes for best results: the default black color for level geometry won't
+show well on the Blueprint wallpaper!
+
 ## Editor Interface
 
 ![Level Editor View](../images/newlevel-2.png)
@@ -108,57 +152,6 @@ Quick 5-second overview of the editor interface:
 
 ---
 
-## Palette Editor
-
-![Screenshot of the Level Palette editor](../images/palette.png)
-
-Clicking the "Tools" menu and "Edit Palette", or the Edit button on the
-palette toolbar on the right side of the screen, will open the palette editor.
-
-Levels are designed to have a limited color palette, and this is your selection
-of colors for the level or doodad you're drawing. You can click on "Add Color"
-to create more rows as needed.
-
-> **NOTICE:** Modifying the color of an existing swatch on your Palette will also
-> change any pixels _already on your level_ to the new color. Drawings in this
-> game use an indexed palette, similar to GIF and some PNG images!
-
-### Color Attributes
-
-The **Attributes** column toggles behaviors on or off for this color. In the default
-color palette, black pixels make up your **solid** level geometry, red pixels are
-**fire**, and blue pixels are **water**.
-
-By default the color will be purely decorative, not physically colliding with the
-player or affecting them in any way.
-
-The attributes and their meanings are:
-
-* **Solid**: the player character and other mobile doodads will collide against
-  pixels drawn in this color. Useful for your level geometry.
-* **Fire**: if the player touches pixels of this color, they die!
-* **Water**: will act like water, currently it just draws the player blue.
-
-### Changing Colors
-
-Clicking on the colored square will prompt you to enter a new color in
-hexadecimal notation, like `#FF00FF` for <span style="color: #FF00FF">magenta</span>
-or `#0099FF` for <span style="color: #0099FF">light blue</span>. Colors can
-be entered in the following formats (the # prefix is actually optional):
-
-* 3-digit hexadecimal: `#F0F` or `#09F`
-* 6-digit hexadecimal: `#0099FF` or `#FC390E`
-* 8-digit RGBA: `#0000FF99` - a color with semi-transparency!
-
-You can set the color to be **semi-transparent** by providing the 8-digit RGBA
-color code; the extra two digits control the transparency between 00 (fully
-invisible) and FF (fully opaque).
-
-![Enter an RGBA color value for see-thru colors](../images/palette-rgba.png)
-
-> Pictured: I have set the "solid" color to #000000**33** giving it an alpha
-> value -- making it semi transparent against the level wallpaper.
-
 ## Doodad Tool
 
 When clicking on the <img src="../images/sprites/actor-tool.png" width="16" height="16"> **Doodad Tool** or
@@ -228,6 +221,70 @@ When the button is released, it sends a "power off" signal and the door closes.
 See the [Doodads](../doodads.md) page for a description of the game's built-in
 doodads and how they interact with each other.
 
+---
+
+## Palette Editor
+
+![Screenshot of the Level Palette editor](../images/palette.png)
+
+The Palette is the set of colors that you draw your actual level with. In your
+default palette, some colors are designated as "solid" and will be used for the
+walls and floors of your level, while others may be "fire" or "water" or just
+decoration (not colliding with the player characters).
+
+You may edit or extend the palette to your liking. By Clicking the "Tools" menu
+and "Edit Palette", or clicking the "Edit" button on the palette toolbar on the
+right side of the screen, you will open the Palette Editor.
+
+Levels are designed to have a limited color palette, and this is your selection
+of colors for the level or doodad you're drawing. You can click on "Add Color"
+to create more rows as needed. There isn't a maximum bounds on number of distinct
+colors, however, the user interface will not accommodate too many of them. This
+game is themed around "hand-drawn maps on paper" and pretend each color is a pen
+or marker and how many distinct colors do you need?
+
+> **NOTICE:** Modifying the color of an existing swatch on your Palette will also
+> change any pixels _already on your level_ to the new color. Drawings in this
+> game use an indexed palette, similar to GIF and some PNG images!
+
+### Color Attributes
+
+The **Attributes** column toggles behaviors on or off for this color. In the default
+color palette, black pixels make up your **solid** level geometry, red pixels are
+**fire**, and blue pixels are **water**.
+
+By default the color will be purely decorative, not physically colliding with the
+player or affecting them in any way.
+
+The attributes and their meanings are:
+
+* **Solid**: the player character and other mobile doodads will collide against
+  pixels drawn in this color. Useful for your level geometry.
+* **Fire**: if the player touches pixels of this color, they die!
+* **Water**: will act like water, currently it just draws the player blue.
+
+### Changing Colors
+
+Clicking on the colored square will prompt you to enter a new color in
+hexadecimal notation, like `#FF00FF` for <span style="color: #FF00FF">magenta</span>
+or `#0099FF` for <span style="color: #0099FF">light blue</span>. Colors can
+be entered in the following formats (the # prefix is actually optional):
+
+* 3-digit hexadecimal: `#F0F` or `#09F`
+* 6-digit hexadecimal: `#0099FF` or `#FC390E`
+* 8-digit RGBA: `#0000FF99` - a color with semi-transparency!
+
+You can set the color to be **semi-transparent** by providing the 8-digit RGBA
+color code; the extra two digits control the transparency between 00 (fully
+invisible) and FF (fully opaque).
+
+![Enter an RGBA color value for see-thru colors](../images/palette-rgba.png)
+
+> Pictured: I have set the "solid" color to #000000**33** giving it an alpha
+> value -- making it semi transparent against the level wallpaper.
+
+---
+
 ## Menu Bar
 
 While editing a level or doodad, a Menu Bar appears at the top of the screen.

mkdocs.yml

@@ -6,6 +6,7 @@ nav:
   - Change History: changes.md
   - Controls: controls.md
   - Creating Levels: custom-levels/index.md
+  - Custom Wallpaper: custom-levels/custom-wallpaper.md
   - Built-in Doodads: doodads.md
   - Linked Doodads: linked-doodads.md
   - Creating Custom Doodads: custom-doodads/index.md

requirements.txt

@@ -0,0 +1 @@
+mkdocs