Update docs for v0.9.0

docs/about.md

@@ -38,4 +38,13 @@ do the job and you can draw whatever shape you want for your level hazards.
 
 While the game ships with a [handful of built-in doodads](doodads.md) to
 spice up your level, you can also create your own and program them to do
-whatever you want, with JavaScript!
+whatever you want, [with JavaScript](custom-doodads/scripts.md)!
+
+The game also has a few "generic" scripts built in that you can choose from,
+to create your own simple doodads with no programming required! In the future,
+template doodads can be created to be able to draw custom player characters,
+Warp Doors and other complex doodads with a script already attached.
+
+Full versions of the game let you bundle custom doodads _inside_ of your
+custom levels for easy sharing to other players. Custom wallpaper images embed
+in a level file for all versions of the game.

docs/changes.md

@@ -1,5 +1,111 @@
 # Changes
 
+## v0.9.0 (TBD)
+
+New features:
+
+* **Touch controls:** the game is now fully playable on small
+  touchscreen devices! For gameplay, touch the middle of the screen
+  to "use" objects and touch anywhere _around_ that to move the
+  player character in that direction. In the level editor, swipe
+  with two fingers to pan and scroll the viewport.
+* **Proper platforming physics:** the player character "jumps" by
+  setting a velocity and letting gravity take care of the rest,
+  rather than the old timer-based flat jump speed approach. Most
+  levels play about the same but the jump reach _is_ slightly
+  different than before!
+* **Giant Screenshot:** in the Level Editor you can take a "Giant
+  Screenshot" of your _entire_ level as it appears in the editor
+  as a large PNG image in your game's screenshots folder. This is
+  found in the "Level" menu in the editor.
+* **Picture-in-Picture Viewport:** in the Level Editor you can open
+  another viewport window into your level. This window can be resized,
+  moved around, and can look at a different part of your level from
+  your main editor window. Mouse over the viewport and your arrow keys
+  scroll it instead of the main window.
+* **"Playtest from here":** if you click and drag from the "Play (P)"
+  button of the level editor, you can drop your player character
+  anywhere you want on your level, and play from there instead of
+  the Start Flag.
+* **Middle-click to pan the level:** holding the middle click button
+  and dragging your mouse cursor will scroll the level in the editor
+  and on the title screen. This can be faster than the arrow keys to
+  scroll quickly!
+* **Zoom in/out** support has come out of "experimental" status. It's
+  still a _little_ finicky but workable!
+
+Some new "technical" doodads are added to the game. These doodads are
+generally invisible during gameplay and have various effects which can
+be useful to set up your level the right way:
+
+* **Goal Region:** a 128x128 region that acts as an Exit Flag and will
+  win the level if touched by the player.
+* **Checkpoint Region:** a 128x128 invisible checkpoint flag that sets
+  the player's spawn point.
+* **Fire Region:** a 128x128 region that triggers the level fail
+  condition, behaving like fire pixels.
+* **Power Source:** a 64x64 invisible source of power. Link it to doodads
+  like the Electric Door and it will emit a power(true) signal on level
+  start, causing the door to "begin" in an opened state.
+* **Stall Player (250ms):** when the player touches this doodad, control
+  freezes for 250ms, one time. If this doodad receives power from a linked
+  button or switch, it will reset the trap, and stall the player once more
+  should they contact it again.
+
+The Doodad Dropper window has a dedicated category for these
+technical doodads.
+
+New methods available to the Doodad JavaScript API:
+
+* `Self.Hide()` and `Self.Show()` to turn invisible and back.
+* `Self.GetVelocity()` that returns a Vector of the actor's current speed.
+* New broadcast message type: `broadcast:ready` (no arguments). Subscribe
+  to this to know the gameplay is ready and you can safely publish messages
+  to your linked doodads or whatever, which could've ended up in deadlocks
+  if done too early!
+
+Some slight UI polish:
+
+* The **Doodad Dropper** window of the level editor now shows a slotted
+  background where there are any empty doodad slots on the current page.
+* Your **scroll position** is remembered when you playtest the level; so
+  coming back to the editor, your viewport into the level as where you
+  left it!
+* New **keybinds** are added to the Level & Doodad Editor:
+    * `Backspace` to close the current popup UI modal
+    * `Shift+Backspace` to close _all_ popup UI modals
+    * `v` to open a new Viewport window
+* Some **flashed messages** are orange instead of blue to denote an 'error'
+  status. The colors of the fonts are softened a bit.
+* New **cheat code**: `show all actors` to make all invisible actors shown
+  during Play Mode. You would be able to see all the technical doodads
+  this way!
+* New command for the doodad CLI tool: `doodad edit-level --remove-actor`
+  to remove actors by name or UUID from a level file.
+
+## v0.8.1 (September 12, 2021)
+
+New features:
+
+* **Enable Experimental Features UI:** in the game's Settings window
+  there is a tab to enable experimental features. It is equivalent to
+  running the game with the `--experimental` option but the setting
+  in-game is persistent across runs of the game.
+* **Zoom In/Out:** the Zoom feature _mostly_ works but has a couple
+  small bugs. The `+` and `-` keys on your number bar (-=) will zoom in
+  or out in the Editor. Press `1` to reset zoom to 100% and press `0`
+  to scroll the level back to origin. These controls are also
+  available in the "View" menu of the editor.
+* **Replace Palette:** with experimental features on it is possible to
+  select a different palette for your already-created level. This will
+  replace colors on your palette until the template palette has been
+  filled in, and pixels already drawn on your level will update too.
+
+Other changes:
+
+* The title screen buttons are more colorful.
+* This release begins to target 32-bit Windows and Linux among its builds.
+
 ## v0.8.0 (September 4, 2021)
 
 This release brings some new features, new doodads, and new levels.

docs/custom-doodads/scripts.md

@@ -1,43 +1,33 @@
 # Doodad Scripts
 
 Doodads are programmed using (ES5) JavaScript which gives them their behavior
-and ability to interact with the player and other doodads.
+and ability to interact with the player and other doodads. Doodad scripts are
+run during "Play Mode" when a level _containing_ the doodad is being played.
 
-Doodad scripts are run during "Play Mode" when a level _containing_ the doodad
+The main() function of your script is called to initialize your doodad. Here
-is being played. You can install a JavaScript (.js) file into a doodad using
+is an example what a doodad script may look like:
-the `doodad` [command line program](../doodad-tool.md) that
-shipped with your game:
-
-```bash
-> doodad install-script index.js filename.doodad
-```
-
-An example Doodad script looks like the following:
 
 ```javascript
-// main() is called on level initialization for each
-// instance ("actor") of the doodad.
 function main() {
     // Logs go to the game's log file (standard output on Linux/Mac).
     console.log("%s initialized!", Self.Title);
 
-    // If our doodad has 'solid' parts that should prohibit movement,
+    // NOTE: you can configure the hitbox in the editor, this function
-    // define the hitbox here. Coordinates are relative so 0,0 is the
+    // can define it in script. This box marks the region you want to
-    // top-left pixel of the doodad's sprite.
+    // be 'solid' or whatever, the hot spot of your doodad.
     Self.SetHitbox(0, 0, 64, 12);
 
     // Handle a collision when another doodad (or player) has entered
-    // the space of our doodad.
+    // the space of our doodad. The `e` has info about the event.
     Events.OnCollide(function(e) {
-        // The `e` object holds information about the event.
         console.log("Actor %s has entered our hitbox!", e.Actor.ID());
 
         // InHitbox is `true` if we defined a hitbox for ourselves, and
         // the colliding actor is inside of the hitbox we defined.
-        if (e.InHitbox) {
         // To prohibit movement, return false from the OnCollide handler.
         // If you don't return false, the actor is allowed to keep on
         // moving through.
+        if (e.InHitbox) {
             return false;
         }
 
@@ -50,6 +40,14 @@ function main() {
         }
     });
 
+    // Subscribe to "broadcast:ready" and don't publish messages
+    // until the game is ready!
+    Message.Subscribe("broadcast:ready", function() {
+        // It is now safe to publish messages to linked doodads, something that
+        // could have deadlocked otherwise!
+        Message.Publish("ping", null);
+    })
+
     // OnLeave is called when an actor, who was previously colliding with
     // us, is no longer doing so.
     Events.OnLeave(function(e) {
@@ -288,6 +286,15 @@ Self.SetVelocity( Velocity(3.2, 7.0) );
 A positive X velocity propels the doodad to the right. A positive Y velocity
 propels the doodad downward.
 
+#### Self.GetVelocity() Velocity
+
+**New in v0.9.0**
+
+Returns the current velocity of the doodad.
+
+Note: for playable characters, velocity is currently managed by the
+game engine.
+
 #### Self.SetMobile(bool)
 
 Call `SetMobile(true)` if the doodad will move on its own.
@@ -317,6 +324,12 @@ Self.SetGravity(true);
 console.log(Self.HasGravity()); // true
 ```
 
+#### Self.Hide(), Self.Show()
+
+**New in v0.9.0**
+
+Hide the current doodad to make it invisible and Show it again.
+
 #### Self.SetInventory(bool)
 
 Set whether this doodad has an inventory and can carry items. Doodads without
@@ -578,6 +591,7 @@ their custom event names.
 | Name | Data Type | Description |
 |------|-----------|--------------|
 | power | boolean | Communicates a "powered" (true) or "not powered" state, as in a Button to an Electric Door. |
+| broadcast:ready | (none) | The level is ready and it is now safe for doodads to publish messages to others. |
 | broadcast:state-change | boolean | An "ON/OFF" button was hit and all state blocks should flip. |
 | broadcast:checkpoint | string | A checkpoint flag was reached. Value is the actor ID of the checkpoint flag. |
 | sticky:down | boolean | A sticky button is pressed Down. If linked to other normal buttons, it tells them to press down as well. Sends a `false` when the Sticky Button itself pops back up. |

docs/custom-levels/custom-wallpaper.md

@@ -36,6 +36,8 @@ from the other three quadrants when decorating these edges of the level:
 * **Tiled Left:** the left margin of the page; tiled vertically across the entire
   left edge of the level.
 
+![Screenshot of how the wallpaper gets tiled out](../images/custom-wallpaper-ex.png)
+
 ## Making a Simple Tiled Wallpaper
 
 If you already have a tiled pattern you want to use as a wallpaper, and want

docs/custom-levels/index.md

@@ -105,6 +105,13 @@ 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!
 
+### Title and Author
+
+After you start editing your level, access the "Level -> Level
+Properties" menu to reopen the level settings and you will find the
+options to edit the Title of your level and change the Author name
+if you like. The default author copies your OS username.
+
 ## Editor Interface
 
 ![Level Editor View](../images/newlevel-2.png)
@@ -226,6 +233,18 @@ doodads and how they interact with each other.
 
 ---
 
+## Giant Screenshot
+
+From the level editor it is possible to create a "Giant Screenshot" of
+your whole entire level and save it as a PNG image. Access this feature
+by clicking on the "Level->Giant screenshot" menu of the editor.
+
+Screenshots are saved in your [profile directory](../profile-directory.md)
+in the 'screenshots' folder; there is a shortcut in the Level menu
+to open the screenshots folder in your file browser.
+
+---
+
 ## Palette Editor
 
 ![Screenshot of the Level Palette editor](../images/palette.png)

docs/custom-levels/publishing.md

@@ -72,6 +72,33 @@ Doodads can be removed from the Attached Files list **if:**
 * The doodad is no longer used in your level, e.g. you have removed every instance
   of the doodad from your level geometry.
 
+In case you can't locate the doodad to remove it from your level, the
+[`doodad` tool](../doodad-tool.md) can remove doodads from your level
+by name or ID:
+
+```bash
+# Show details of all the actors in this level;
+# look for the Actors section of the output.
+$ 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
+...
+
+# Remove all instances of a doodad by name
+$ doodad edit-level --remove-actor crumbly-floor.doodad example.level
+```
+
 ### Removing Attached Wallpapers
 
 Similarly: if the level is using a custom wallpaper image, you can not remove

docs/doodad-tool.md

@@ -212,6 +212,47 @@ Available properties that can be modified are as follows:
     * `--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
+```
 
 ---
 

docs/doodads.md

@@ -41,6 +41,12 @@ linked together in your levels.
     * [State Button](#state-button)
     * [State Blocks](#state-blocks)
     * [Blue & Orange Warp Doors](#blue-orange-warp-doors)
+* [Technical Doodads](#technical-doodads)
+    * [Goal Region](#goal-region)
+    * [Checkpoint Region](#checkpoint-region)
+    * [Fire Region](#fire-region)
+    * [Power Source](#power-source)
+    * [Stall Player](#stall-player)
 
 ---
 
@@ -420,3 +426,50 @@ a de-activated door.
 
 The **Blue Warp Door** is active at the same time as the **Blue State Blocks**,
 and vice versa for the **Orange Warp Door.**
+
+---
+
+## Technical Doodads
+
+"Technical" doodads tend to turn invisible during gameplay and have some useful
+interactions for certain situations.
+
+### Goal Region
+
+![Goal Region](images/doodads/goal-region.png)
+
+This doodad acts like an invisible Exit Flag, winning the level if touched by
+a player character.
+
+### Checkpoint Region
+
+![Checkpoint Region](images/doodads/checkpoint-region.png)
+
+This doodad acts like an invisible Checkpoint Flag, recording the player's
+progress in a level.
+
+### Fire Region
+
+![Fire Region](images/doodads/fire-region.png)
+
+This doodad will trigger the fail condition if touched by the player.
+
+### Power Source
+
+![Power Source](images/doodads/power-source.png)
+
+On level start, this doodad emits a `power(true)` signal to all linked doodads.
+Connect it to an Electric Door, for example, and the door will open immediately
+when the level begins.
+
+### Stall Player
+
+![Stall Player](images/doodads/stall-player.png)
+
+This doodad will freeze the player character for 250ms, one time. It is useful
+if you need to slow down the player to get some timing in your level to work
+out.
+
+If this doodad receives power from a linked button, it will reset the trap,
+and will freeze the player again for 250ms should they make contact with the
+doodad again.

docs/hacking.md

@@ -102,6 +102,10 @@ The following commands are supported:
 
     Flashes your custom message on the bottom of the screen.
 
+* `error <message>`
+
+    Flash your message in the error color.
+
 * `alert <message>`
 
     Pop up an alert box modal with a custom message.
@@ -170,6 +174,13 @@ open the developer console and type:
     will also enable antigravity, otherwise you would fall to the
     bottom of the level.
 
+* `show all actors`
+
+    Run this during Play Mode to make all invisible actors visible. For
+    example, you'll be able to see all of the Technical Doodads which
+    normally turn themselves invisible, or you can reveal the player
+    character during Warp Door transitions.
+
 * `give all keys`
 
     Gives all four colored keys to the player.
@@ -208,7 +219,7 @@ line of JavaScript code.
 >$ 2 + 2
 4
 >$ d.Flash("This is %s", d.Title())
-This is Project: Doodle v0.4.0-alpha
+This is Sketchy Maze v0.9.0
 ```
 
 The following native objects are exposed to the JavaScript shell:
@@ -217,6 +228,7 @@ The following native objects are exposed to the JavaScript shell:
 * `function RGBA(red, green, blue, alpha uint8)` creates a native
   Color type, each value is range 0 to 255
 * `function Point(x, y int)` creates a native Point type.
+* `function Vector(x, y float64)` creates a native Vector type.
 * `function Rect(x, y, w, h int)` creates a native Rect type.
 * `function Tree(ui.Widget)` prints a tree of UI widgets drawn on the
   screen -- if you can find the widgets somewhere under `d`

docs/hotkeys.md

@@ -25,30 +25,58 @@ Only while editing a level or doodad:
 | Arrows   | Scroll the view of the level you're editing.         |
 | `p`      | Playtest the current level (press `e` to edit again) |
 | `d`      | Open the Doodads window to drop them in your level   |
+| `v`      | Open a new Viewport window into your level           |
 | `f`      | Pencil Tool (**f**reehand)                           |
 | `l`      | **L**ine Tool                                        |
 | `r`      | **R**ectangle Tool                                   |
 | `c`      | Ellipse Tool (**c**ircles)                           |
 | `x`      | Eraser Tool                                          |
-| `+=`     | Zoom in (with [--experimental](experimental.md))     |
+| `+=`     | Zoom in                                              |
-| `-_`     | Zoom out ([--experimental](experimental.md))         |
+| `-_`     | Zoom out                                             |
-| `1`      | Reset zoom ([--experimental](experimental.md))       |
+| `1`      | Reset zoom                                           |
 | `0`      | Scroll level back to origin (0,0)                    |
+| `Backspace` | Close the top-most popup window.                  |
+| `Shift+Backspace` | Close _all_ popup windows.                  |
 | `Ctrl-N` | Create a new level                                   |
 | `Ctrl-S` | Save the current drawing                             |
 | `Ctrl-O` | Open a drawing                                       |
 | `Ctrl-Z` | Undo                                                 |
 | `Ctrl-Y` | Redo                                                 |
 
+ 
+
+### Mouse gestures
+
+* Middle-click + drag: pan scroll the level viewport.
+
+### Multi-touch gestures
+
+* Two-finger drag: pan scroll the level viewport.
+
 ---
 
 ## Gameplay Only
 
+### Keyboard controls
+
 | Key            | Action                                       |
-|---------|----------------------------------------------------------|
+|----------------|----------------------------------------------|
-| `Left`  | Move the player character towards the left.              |
+| `Left` or `a`  | Move the player character towards the left.  |
-| `Right` | Move the player character towards the right.             |
+| `Right` or `d` | Move the player character towards the right. |
-| `Up`    | Jump                                                     |
+| `Up` or `w`    | Jump                                         |
-| `e`     | Return to the level editor (only if you game from there) |
+| `Down` or `s`  | Move the player downward (antigravity only)  |
+| `e`            | Return to the level editor                   |
+
+ 
+
+### Touch controls
+
+* Touch the "middle" of the screen to open Warp Doors or use other
+  objects that the player character is nearby.
+* Touch anywhere **left** of that "middle" to move left, and touch
+  **right** of that "middle" to move right.
+* Touch anywhere **above** that middle to jump. The left and right
+  regions of the screen will jump and move in that direction.
+* For antigravity, touch anywhere **below** to move downward.
 
  

docs/index.md

@@ -7,7 +7,7 @@ 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:** Sept. 3, 2021 for Sketchy Maze v0.8.0.
+**Last Updated:** Oct. 8, 2021 for Sketchy Maze v0.9.0.
 
 ## Table of Contents
 

docs/profile-directory.md

@@ -7,7 +7,7 @@ This will typically be found at the following locations based on your platform:
 
 * **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`
+* **GNU/Linux:** `$XDG_CONFIG_HOME/doodle` or `$HOME/.config/doodle`
 * **Linux (Flatpak):** `$HOME/.var/app/com.sketchymaze.Doodle/config/doodle`
 
 ## Opening your Profile Directory