Update docs for v0.9.0

This commit is contained in:
Noah 2021-10-08 18:35:52 -07:00
parent 63f069bf8e
commit e957a331bb
21 changed files with 346 additions and 35 deletions

View File

@ -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.

View File

@ -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:

View File

@ -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. |

View File

@ -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

View File

@ -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)

View File

@ -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

View File

@ -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
```
---

View File

@ -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.

View File

@ -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`

View File

@ -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 |
&nbsp;
### 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 |
&nbsp;
### 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.
&nbsp;

Binary file not shown.

Before

Width:  |  Height:  |  Size: 54 KiB

After

Width:  |  Height:  |  Size: 65 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 100 KiB

After

Width:  |  Height:  |  Size: 127 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 956 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 965 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 990 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 780 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.1 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 110 KiB

After

Width:  |  Height:  |  Size: 84 KiB

View File

@ -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

View File

@ -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