Update Guidebook for v0.7.0

docs/changes.md

@@ -1,5 +1,56 @@
 # Changes
 
+## v0.7.0 (June 20 2021)
+
+This is the first release of the game where the "free version" drifts meaningfully
+away from the "full version". Free versions of the game will show the label
+"(shareware)" next to the game version numbers and will not support embedding
+doodads inside of level files -- for creating them or playing them.
+Check the website for how you can register the full version of the game.
+
+This release brings several improvements to the game:
+
+* **Brush Patterns** for your level palette. Instead of your colors drawing on as
+  plain, solid pixels, a color swatch can _sample_ with a Pattern to create a
+  textured appearance when plotted on your level. Several patterns are built in
+  including Noise, Marker, Ink, and others. The idea is that your brush strokes can
+  look as though they were drawn in pencil graphite or similar.
+* **Title Screen:** the demo level shown on the title screen will leisurely scroll
+  around the page. The arrow keys may still manually scroll the level any direction.
+* **Attach Doodads to Level Files:** this is the first release that supports _truly_
+  portable custom levels! By attaching your custom doodads _with_ your custom level
+  file, it will "just play" on someone else's computer, and they don't need to copy
+  all your custom doodads for it to work! But, free versions of the game will not
+  get to enjoy this feature.
+* **Settings UI**: a "Settings" button on the home screen (or the Edit->Settings
+  menu in the editor) will open a settings window. Check it out!
+* **Horizontal Toolbars option:** if enabled in the Settings window, the toolbar
+  and palette in the Editor will be horizontal instead of vertical, along the top
+  and bottom of the screen. This may be better optimized for smartphone-sized
+  screens like the Pinephone. If the program is started with `-w mobile` the first
+  time, it will use horizontal toolbars by default.
+
+Some small bits of polish in the game's user interface:
+
+* Some buttons are more colorful! The "Ok" button in alert boxes is blue and pressing
+  Enter will select the blue button.
+* When opening a drawing to play or edit, a blue **Browse...** button is
+  added so you can more easily find downloaded custom levels and play them.
+* In the Level Editor, the "Level ->  **Attached Files**" menu will let you see
+  and manage files attached to your level, such as its custom wallpaper image or
+  any custom doodads that were published with the level.
+* The keyboard shortcut to open the developer console is now the tilde/grave key
+  (`) instead of Enter.
+
+Bugs fixed:
+
+* The WASD keys to move the player character (as an alternative to the arrow keys)
+  now works more reliably. Previously, they were affected by key-repeat so Boy would
+  do a quick hop followed by a longer one when pressing W to jump. Also, his
+  animation would not update correctly when moving via the WASD keys. Both bugs
+  are fixed in this release.
+* Shortcut keys advertised in the menu, such as Ctrl-N and Ctrl-S, now actually work.
+
 ## v0.6.0-alpha (June 6 2021)
 
 This release brings less jank and some new features.

docs/controls.md

@@ -4,6 +4,12 @@
 will be usable from gamepad controllers, especially if it branches out and
 targets platforms other than desktop computers in the future.
 
+The list of controls is also viewable in-game in the Settings Window, accessible
+from the title screen or the Edit->Settings menu of the editor. The controls can
+not be customized at this time.
+
+![Controls UI](images/controls.png)
+
 ## During Gameplay
 
 While playing a level, the following keys are used to control the player character:

docs/custom-doodads/index.md

@@ -13,6 +13,33 @@ image editor. Then, you can program their behavior using JavaScript to make them
 * Program its Behavior
     * [JavaScript](scripts.md)
 
+## Naming Convention
+
+It is strongly encouraged that you name your custom doodad files with a
+prefix or something to _namespace_ them apart from the built-in doodads.
+
+For example: if you made a custom doodad named "door-red.doodad" it would
+actually conflict with the [built-in doodad](../doodads.md) of the same
+name, and your custom doodad would take priority over the built-in one.
+
+By prefixing your custom doodad filenames with your initials or name, you
+will minimize the likelihood that your doodad conflicts with a built-in
+from a future game release _or_ with custom doodads made by other players
+than yourself.
+
+Future versions of the game will likely prevent saving a new doodad with
+the same filename of a built-in one.
+
+## Profile Directory
+
+Custom doodads and levels will go in your [Profile Directory](../profile-directory.md),
+into folders named "doodads" and "levels" respectively.
+
+To share your custom doodads with others, you can copy the `.doodad` files out
+of your doodads folder. To install doodads made by others, place their `.doodad`
+files into your doodads folder, and they will appear in-game to drag and drop
+them into your level.
+
 ## doodad (Command Line Tool)
 
 Your copy of the game should have shipped with a `doodad` command-line tool

docs/custom-levels/index.md

@@ -247,6 +247,22 @@ or marker and how many distinct colors do you need?
 > 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!
 
+### Brush Patterns
+
+A color swatch on your palette may have a Brush Pattern (labeled "Tex") applied
+to it which will vary the look of your color once drawn onto your level. For
+example, instead of a red color drawing on as solid red pixels, it can take on
+a more noisy pattern resembling colored pencil graphite or marker.
+
+![Screenshot showing various brush patterns](../images/patterns.png)
+
+The pattern when drawn onto your level is a cosmetic-only effect: you can change
+the pattern after the fact, or remove the pattern altogether, and your level
+immediately updates.
+
+In the future, you will be able to add your own custom pattern images but for
+now there are a handful of built-in options to choose from.
+
 ### Color Attributes
 
 The **Attributes** column toggles behaviors on or off for this color. In the default
@@ -280,9 +296,6 @@ 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
@@ -295,26 +308,30 @@ Its options include:
     * New doodad
     * Save (Ctrl-S)
     * Save as...
+    * Publish level (attach custom doodads for easy sharing)
     * Open... (Ctrl-O)
     * Close level
     * Quit (Escape)
 * **Edit**
     * Undo (Ctrl-Z)
     * Redo (Ctrl-Y)
+    * Settings
 * **Level**
     * Page settings (to change the level type or wallpaper)
+    * Attached files
     * Playtest (P)
 * **Tools**
     * Debug overlay (F3)
     * Command shell (Enter)
     * Edit Palette
-    * Doodads (d)
     * Pencil Tool (f)
     * Line Tool (L)
     * Rectangle Tool (r)
     * Ellipse Tool (c)
     * Eraser Tool (x)
+    * Doodads (d)
     * Link Tool
 * **Help**
     * User Manual (F1)
+    * Register
     * About

docs/custom-levels/publishing.md

@@ -0,0 +1,84 @@
+# Publishing Levels
+
+Sketchy Maze is designed to be _very_ friendly to mods and custom user content,
+and the **Publish Level** feature is an important part towards that goal.
+
+When you have created your own level and you have added some
+[custom doodads](../custom-doodads/index.md) to it, **publishing** your level
+means that your custom doodads will _attach_ directly into the level file for
+easy sharing with others: another player can download _just_ your `.level` file
+and it will "just play" in their copy of the game, and they don't need to track
+down all the same custom doodads you've used.
+
+> <em>**Notice:** This feature is only available for full (registered) versions of the
+> game. The free (shareware) version of </em>Sketchy Maze<em> supports custom levels
+> and doodads, but you would need to copy the custom `.doodad` files to each
+> computer your level will play on, otherwise the game won't be able to find
+> them! Check [the website](https://www.sketchymaze.com/) for details how to acquire
+> a full version of the game.</em>
+
+## Publish a Level
+
+When you are ready to share your level, click on the "File->Publish level" menu
+option in the Level Editor.
+
+![Publish Window screenshot](../images/publish.png)
+
+The Publish window will show the list of named doodads which currently exist in
+your level, designating which doodads are _custom_ and which were built-in with
+the game (the built-in doodads are shown in blue text plus an asterisk* symbol).
+
+The blue **Export Level** button will prompt for you to give a file name, and
+the level will be written there _with_ all of its custom doodads embedded inside.
+
+Optionally, you can choose to "Attach built-in doodads too" -- this will attach
+copies of the built-in doodads to your level, too, which will override the game's
+_actual_ built-in doodads. Doing this comes with some pros and cons:
+
+* **Pro:** if future releases of _Sketchy Maze_ change the behavior or appearance
+  of a built-in doodad, your custom level will still use the older version that
+  it was published with.
+* **Con:** if future updates to a built-in doodad have improved its appearance,
+  added functionality or fixed bugs, the published level will not benefit from
+  that update because it brought its own (older) version of the built-in doodad.
+
+## Managing Attached Files
+
+You can view and manage the files attached to a level by clicking on the
+"Level -> Attached files" menu in the level editor:
+
+![Attached Files screenshot](../images/attachments.png)
+
+This window lists the doodads, wallpapers or other custom assets which have been
+attached directly _into_ the level file. A published level will have all of its
+custom doodads attached (and possibly copies of the built-in doodads it used),
+as well as the [custom wallpaper](custom-wallpaper.md) image (if any).
+
+### Removing Attached Doodads
+
+Attached doodads may be removed from the level **if** doing so will not break
+the level. Generally, this means: if an instance of that doodad is still in
+use _somewhere_ on your level, and removing the doodad from the Attached Files
+would cause the level to be unable to locate that doodad, then removing it from
+your level will not be permitted.
+
+Doodads can be removed from the Attached Files list **if:**
+
+* They are built-in doodads; removing them will cause the level to go back to
+  using the built-in copies of these doodads instead.
+* They are custom doodads **and** you have them in your [profile directory](../profile-directory.md):
+  the level will start using the named doodad from your profile directory (similarly
+  to how you designed the level in the first place, before publishing!)
+* The doodad is no longer used in your level, e.g. you have removed every instance
+  of the doodad from your level geometry.
+
+### Removing Attached Wallpapers
+
+Similarly: if the level is using a custom wallpaper image, you can not remove
+the wallpaper from the Attached Files list while the level is still using it.
+
+To remove the wallpaper image, you need to:
+
+1. Go into the Page Settings (Level->Page settings menu) and select one of the
+   built-in wallpaper images, such as "Notebook."
+2. Then you can remove the custom wallpaper image from the Attached Files window.

docs/doodad-tool.md

@@ -1,4 +1,4 @@
-# Doodad Tool
+# Doodad Program
 
 The game ships with a command-line program called `doodad` which assists in
 creating and managing custom doodads and levels.
@@ -34,32 +34,35 @@ subcommand and `--help` to get help on that command, for example:
 doodad convert --help
 ```
 
+---
+
 ## Examples
 
 Here are some common scenarios and use cases for the doodad tool.
 
-### Show
+### Show Level or Doodad Information
+
+Shows metadata and details about a level or doodad file.
 
 ```bash
 # Usage:
 doodad show [doodad or level filename]
 ```
 
-Shows metadata and details about a level or doodad file.
-
 Examples:
 
 ```bash
+### About a doodad file
 $ doodad show button.doodad
 ===== Doodad: button.doodad =====
 Headers:
   File version: 1
-  Game version: 0.0.10-alpha
+  Game version: 0.7.0
   Doodad title: Button
         Author: Noah
         Locked: true
         Hidden: false
-   Script size: 473 bytes
+   Script size: 922 bytes
 
 Palette:
   - Swatch name: Color<#000000+ff>
@@ -87,15 +90,143 @@ Chunks:
   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
 ```
 
-### Convert
+---
+
+### 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
@@ -107,17 +238,61 @@ file "custom.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
 ```
 
-#### Create a level from a PNG image
+Some considerations about this feature:
 
-```bash
+* Doodads are **not** included in the output image; only the level geometry
-doodad convert level.png output.level
+  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.

docs/hacking.md

@@ -65,15 +65,16 @@ Supported variables include:
 
 ## Developer Console
 
-Pressing the `Enter` key at any time will open the developer console at the
+Pressing the tilde/grave key (<code>`</code>) at any time will open the developer
-bottom of the screen (all gameplay logic is paused while the console is open).
+console at the bottom of the screen (all gameplay logic is paused while the
+console is open).
 
 In the console you can type anything from simple commands, to hidden cheat
 codes, to JavaScript commands to operate on some of the game's internal code!
 
 ![Screenshot of the developer console](images/shell.png)
 
-Pressing `Enter` again without typing a command will close the console.
+Pressing `Enter` without typing a command will close the console.
 
 ## Commands
 

docs/hotkeys.md

@@ -12,7 +12,7 @@ Here are all the hotkeys/shortcuts used within Sketchy Maze.
 |----------|------------------------------------------------------------|
 | `Escape` | Exit the application (after confirmation modal).           |
 | `F1`     | Open the Guidebook (this site).                            |
-| `Enter`  | Open the [developer console](hacking.md#developer-console) |
+| <code>`</code> | Open the [developer console](hacking.md#developer-console) |
 
 ---
 

docs/index.md

@@ -7,11 +7,16 @@ 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, play it and share your
 levels with others.
 
+**Last Updated:** June 20, 2021 for Sketchy Maze v0.7.0.
+
 ## Table of Contents
 
 * [About Sketchy Maze](about.md)
+    * [Change History](changes.md)
 * [Gameplay Controls](controls.md)
 * [Creating Custom Levels](custom-levels/index.md)
+    * [Publishing Levels](custom-levels/publishing.md)
+    * [Custom Wallpaper](custom-levels/custom-wallpaper.md)
 * [The Built-in Doodads](doodads.md)
 * [Linked Doodads](linked-doodads.md)
 * [Creating Custom Doodads](custom-doodads/index.md)
@@ -21,4 +26,5 @@ levels with others.
 * [Shortcut Keys](hotkeys.md)
 * [The `doodad` command-line tool](doodad-tool.md)
 * [Hacking and debugging](hacking.md)
+    * [Profile Directory](profile-directory.md)
 * [Open Source Licenses](licenses.md)

docs/profile-directory.md

@@ -5,6 +5,21 @@ operating system's profile directory for your account.
 
 This will typically be found at the following locations based on your platform:
 
-* **Linux:** `$XDG_CONFIG_HOME` or `$HOME/.config/doodle`
 * **Windows:** `%APPDATA%` or `C:\Users\%USER%\AppData\Roaming\doodle`
 * **Mac OS:** `$HOME/Library/Application Support/doodle`
+* **GNU/Linux:** `$XDG_CONFIG_HOME` or `$HOME/.config/doodle`
+* **Linux (Flatpak):** `$HOME/.var/app/com.sketchymaze.Doodle/config/doodle`
+
+## Opening your Profile Directory
+
+The in-game Settings window has a button that will open your Profile Directory
+in your operating system's default file browser. You will see the folders
+labeled "levels" and "doodads" which is where your custom created content will
+live.
+
+To install custom content created by other players, copy them into these folders.
+
+## See Also
+
+* [Publishing Levels](custom-levels/publishing.md): embed custom doodads directly
+  _inside_ your level for easy sharing with others!

mkdocs.yml

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