diff --git a/docs/about.md b/docs/about.md index cc47baa..c0ce7f9 100644 --- a/docs/about.md +++ b/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. \ No newline at end of file diff --git a/docs/changes.md b/docs/changes.md index 87ae450..0df9708 100644 --- a/docs/changes.md +++ b/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. @@ -243,7 +349,7 @@ 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 + 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: diff --git a/docs/custom-doodads/scripts.md b/docs/custom-doodads/scripts.md index 7bcde8c..5438cb6 100644 --- a/docs/custom-doodads/scripts.md +++ b/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 -is being played. You can install a JavaScript (.js) file into a doodad using -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: +The main() function of your script is called to initialize your doodad. Here +is an example what a doodad script may look like: ```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, - // define the hitbox here. Coordinates are relative so 0,0 is the - // top-left pixel of the doodad's sprite. + // NOTE: you can configure the hitbox in the editor, this function + // can define it in script. This box marks the region you want to + // 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. + // 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) { - // To prohibit movement, return false from the OnCollide handler. - // If you don't return false, the actor is allowed to keep on - // moving through. 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. | diff --git a/docs/custom-levels/custom-wallpaper.md b/docs/custom-levels/custom-wallpaper.md index de14f37..ad396ac 100644 --- a/docs/custom-levels/custom-wallpaper.md +++ b/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 diff --git a/docs/custom-levels/index.md b/docs/custom-levels/index.md index 10e36b6..5f743a5 100644 --- a/docs/custom-levels/index.md +++ b/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) diff --git a/docs/custom-levels/publishing.md b/docs/custom-levels/publishing.md index 75b19d7..d550d56 100644 --- a/docs/custom-levels/publishing.md +++ b/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 diff --git a/docs/doodad-tool.md b/docs/doodad-tool.md index de8a801..9c0e3b4 100644 --- a/docs/doodad-tool.md +++ b/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 `: 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 +``` --- diff --git a/docs/doodads.md b/docs/doodads.md index 3f22c52..628c15f 100644 --- a/docs/doodads.md +++ b/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. \ No newline at end of file diff --git a/docs/hacking.md b/docs/hacking.md index 3e98a9d..1c18238 100644 --- a/docs/hacking.md +++ b/docs/hacking.md @@ -102,6 +102,10 @@ The following commands are supported: Flashes your custom message on the bottom of the screen. +* `error ` + + Flash your message in the error color. + * `alert ` 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` diff --git a/docs/hotkeys.md b/docs/hotkeys.md index 11def33..fce9303 100644 --- a/docs/hotkeys.md +++ b/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 out ([--experimental](experimental.md)) | -| `1` | Reset zoom ([--experimental](experimental.md)) | +| `+=` | Zoom in | +| `-_` | Zoom out | +| `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 -| Key | Action | -|---------|----------------------------------------------------------| -| `Left` | Move the player character towards the left. | -| `Right` | Move the player character towards the right. | -| `Up` | Jump | -| `e` | Return to the level editor (only if you game from there) | +### Keyboard controls + +| Key | Action | +|----------------|----------------------------------------------| +| `Left` or `a` | Move the player character towards the left. | +| `Right` or `d` | Move the player character towards the right. | +| `Up` or `w` | Jump | +| `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.   diff --git a/docs/images/about.png b/docs/images/about.png index ce522a4..e620e8b 100644 Binary files a/docs/images/about.png and b/docs/images/about.png differ diff --git a/docs/images/custom-wallpaper-ex.png b/docs/images/custom-wallpaper-ex.png new file mode 100644 index 0000000..b0d4980 Binary files /dev/null and b/docs/images/custom-wallpaper-ex.png differ diff --git a/docs/images/debugging.png b/docs/images/debugging.png index 56177c7..eb25ced 100644 Binary files a/docs/images/debugging.png and b/docs/images/debugging.png differ diff --git a/docs/images/doodads/checkpoint-region.png b/docs/images/doodads/checkpoint-region.png new file mode 100644 index 0000000..13766e6 Binary files /dev/null and b/docs/images/doodads/checkpoint-region.png differ diff --git a/docs/images/doodads/fire-region.png b/docs/images/doodads/fire-region.png new file mode 100644 index 0000000..117a231 Binary files /dev/null and b/docs/images/doodads/fire-region.png differ diff --git a/docs/images/doodads/goal-region.png b/docs/images/doodads/goal-region.png new file mode 100644 index 0000000..c93dd3c Binary files /dev/null and b/docs/images/doodads/goal-region.png differ diff --git a/docs/images/doodads/power-source.png b/docs/images/doodads/power-source.png new file mode 100644 index 0000000..14a743c Binary files /dev/null and b/docs/images/doodads/power-source.png differ diff --git a/docs/images/doodads/stall-player.png b/docs/images/doodads/stall-player.png new file mode 100644 index 0000000..ea0bd5e Binary files /dev/null and b/docs/images/doodads/stall-player.png differ diff --git a/docs/images/main-menu.png b/docs/images/main-menu.png index 626e601..85f5ae9 100644 Binary files a/docs/images/main-menu.png and b/docs/images/main-menu.png differ diff --git a/docs/index.md b/docs/index.md index 1c0c453..ed481d1 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/profile-directory.md b/docs/profile-directory.md index f568031..98a8abf 100644 --- a/docs/profile-directory.md +++ b/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