Browse Source

Update Guidebook for v0.7.0

master
Noah Petherbridge 3 years ago
parent
commit
6f7e14df1e
  1. 51
      docs/changes.md
  2. 6
      docs/controls.md
  3. 27
      docs/custom-doodads/index.md
  4. 25
      docs/custom-levels/index.md
  5. 84
      docs/custom-levels/publishing.md
  6. 197
      docs/doodad-tool.md
  7. 7
      docs/hacking.md
  8. 2
      docs/hotkeys.md
  9. BIN
      docs/images/attachments.png
  10. BIN
      docs/images/controls.png
  11. BIN
      docs/images/doodads.png
  12. BIN
      docs/images/link-tool.png
  13. BIN
      docs/images/main-menu.png
  14. BIN
      docs/images/newlevel-2.png
  15. BIN
      docs/images/palette-rgba.png
  16. BIN
      docs/images/palette.png
  17. BIN
      docs/images/patterns.png
  18. BIN
      docs/images/publish.png
  19. 6
      docs/index.md
  20. 17
      docs/profile-directory.md
  21. 1
      mkdocs.yml

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

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

27
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

25
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

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

197
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
```
#### Convert a level to a PNG image
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
doodad convert my.level output.png
# 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
```
#### Create a level from a PNG image
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
doodad convert level.png output.level
# Usage:
doodad convert my.level output.png
```
Some considerations about this feature:
* Doodads are **not** included in the output image; only the level geometry
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.

7
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
bottom of the screen (all gameplay logic is paused while the console is open).
Pressing the tilde/grave key (<code>`</code>) at any time will open the developer
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

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

BIN
docs/images/attachments.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 83 KiB

BIN
docs/images/controls.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 83 KiB

BIN
docs/images/doodads.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 66 KiB

BIN
docs/images/link-tool.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 62 KiB

After

Width:  |  Height:  |  Size: 65 KiB

BIN
docs/images/main-menu.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 70 KiB

After

Width:  |  Height:  |  Size: 69 KiB

BIN
docs/images/newlevel-2.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 69 KiB

After

Width:  |  Height:  |  Size: 69 KiB

BIN
docs/images/palette-rgba.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 89 KiB

After

Width:  |  Height:  |  Size: 126 KiB

BIN
docs/images/palette.png

Binary file not shown.

Before

Width:  |  Height:  |  Size: 75 KiB

After

Width:  |  Height:  |  Size: 108 KiB

BIN
docs/images/patterns.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 94 KiB

BIN
docs/images/publish.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

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

17
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!

1
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

Loading…
Cancel
Save