diff --git a/Makefile b/Makefile index fa0af5d..eb29885 100644 --- a/Makefile +++ b/Makefile @@ -121,7 +121,8 @@ dist-free: doodads bindata build-free __dist-common __dist-common: mkdir -p dist/doodle-$(VERSION) cp bin/* dist/doodle-$(VERSION)/ - cp -r README.md Changes.md "Open Source Licenses.md" dist/doodle-$(VERSION)/ + cp -r README.md Changes.md "Open Source Licenses.md" rtp dist/doodle-$(VERSION)/ + rm -rf dist/doodle-$(VERSION)/rtp/.git cd dist && tar -czvf doodle-$(VERSION).tar.gz doodle-$(VERSION) cd dist && zip -r doodle-$(VERSION).zip doodle-$(VERSION) diff --git a/dev-assets/guidebook/Makefile b/dev-assets/guidebook/Makefile new file mode 100644 index 0000000..95ca53b --- /dev/null +++ b/dev-assets/guidebook/Makefile @@ -0,0 +1,16 @@ +SHELL := /bin/bash + +# `make serve` to serve the mkdocs site on localhost. +.PHONY: serve +serve: + mkdocs serve + +# `make build` to build the static documentation site. +.PHONY: build +build: + mkdocs build + +# `make clean` cleans everything up. +.PHONY: clean +clean: + rm -rf site diff --git a/dev-assets/guidebook/compiled/index.html b/dev-assets/guidebook/compiled/index.html deleted file mode 100644 index cabb96c..0000000 --- a/dev-assets/guidebook/compiled/index.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - Project: Doodle Guidebook - - - - - - - - -
-
- -
-
- - - \ No newline at end of file diff --git a/dev-assets/guidebook/docs/about.md b/dev-assets/guidebook/docs/about.md new file mode 100644 index 0000000..e501178 --- /dev/null +++ b/dev-assets/guidebook/docs/about.md @@ -0,0 +1,3 @@ +# About Project: Doodle + +Lorem ipsum. diff --git a/dev-assets/guidebook/docs/custom-doodads/edit-external.md b/dev-assets/guidebook/docs/custom-doodads/edit-external.md new file mode 100644 index 0000000..3e253ff --- /dev/null +++ b/dev-assets/guidebook/docs/custom-doodads/edit-external.md @@ -0,0 +1,20 @@ +# Drawing Doodads in an External Program + +Doodad sprites can be drawn using any image editor and saved as .png files +(with transparency). You can then create a doodad file from your series of +PNG images. + +Most of the built-in doodads that ship with the game were created in this way. + +## Create a Doodad from Images + +Save each frame of your doodad as a separate PNG image and then use the `doodad` +command-line tool to convert them to a `.doodad` file. + +```bash +# Usage: +doodad convert [options] + +# Example: +doodad convert door-closed.png door-open.png door.doodad +``` diff --git a/dev-assets/guidebook/docs/custom-doodads/edit-in-game.md b/dev-assets/guidebook/docs/custom-doodads/edit-in-game.md new file mode 100644 index 0000000..f26901e --- /dev/null +++ b/dev-assets/guidebook/docs/custom-doodads/edit-in-game.md @@ -0,0 +1,27 @@ +# Drawing a Doodad In-Game + +Project: Doodle has some **limited** support to draw your doodad sprites +in-game. Currently you can only draw one frame (image) for the doodad +and save it to disk. + +To start a new doodad, open the game and enter the level editor. + +Select the "New Doodad" button at the top of the screen to start drawing a +new doodad. Choose the size (square) of its sprite when prompted. + +Doodads saved in-game go in your user config directory for the game. On Linux, +this is at ~/.config/doodle. + +If you want to create a doodad with multiple frames (to animate it or have +varying states that change the doodad's appearance in the level), the +`doodad` tool is recommended. See +[drawing images in an external program](edit-external.md). + +## Future Planned Features + +Creating doodads in-game is intended to be a fully supported feature. The +following features are planned to be supported: + +* Support editing multiple frames instead of only the first frame. +* Implement some features only available on the `doodad` tool using in-game + UI, such as attaching JavaScripts to the doodad. diff --git a/dev-assets/guidebook/docs/custom-doodads/index.md b/dev-assets/guidebook/docs/custom-doodads/index.md new file mode 100644 index 0000000..67fa6fc --- /dev/null +++ b/dev-assets/guidebook/docs/custom-doodads/index.md @@ -0,0 +1,43 @@ +# Creating Custom Doodads + +Project: Doodle is designed to be modder friendly and provides tools to help +you create your own custom doodads to use in your levels. + +You can draw the sprites for the doodad either in-game or using an external +image editor. Then, you can program their logic using JavaScript to make them +"do" stuff in-game and interact with the player and other doodads. + +* Drawing your Doodad's Sprites + * [In-Game](edit-in-game.md) + * [In an External Program](edit-external.md) +* Program its Behavior + * [JavaScript](scripts.md) + +## doodad (Command Line Tool) + +Your copy of the game should have shipped with a `doodad` command-line tool +bundled with it. On Windows it's called `doodad.exe` and should be in the same +folder as the game executable. On Mac OS, it is inside the .app bundle. + +The `doodad` tool provides a command-line interface to create and inspect +doodad and level files from the game. You'll need to use this tool, at the very +least, to attach a JavaScript to your doodad to make it "do" stuff in-game. + +You can create a doodad from PNG images on disk, attach or view the JavaScript +source on them, and view/edit metadata. + +```bash +# (the $ represents the shell prompt in a command-line terminal) + +# See metadata about a doodad file. +$ doodad show /path/to/custom.doodad + +# Create a new doodad based on PNG images on disk. +$ doodad convert frame0.png frame1.png frame2.png output.doodad + +# Add and view a custom script attached to the doodad. +$ doodad install-script index.js custom.doodad +$ doodad show --script custom.doodad +``` + +More info on the [`doodad` tool](../doodad-tool.md) here. diff --git a/dev-assets/guidebook/docs/custom-levels/index.md b/dev-assets/guidebook/docs/custom-levels/index.md new file mode 100644 index 0000000..cd9369e --- /dev/null +++ b/dev-assets/guidebook/docs/custom-levels/index.md @@ -0,0 +1,99 @@ +# Creating Custom Levels + +One of the core gameplay features is its Level Editor which lets you draw your +own custom maps to play and share with others. + +From the game's Main Menu, click on the "Create a Level" button to open the +level editor. To edit an existing custom level, click on the "Edit a Level" +button instead. + +## Level Properties + +When creating a new level, you first choose some settings for it. These are +described below: + +### Page Type + +This setting controls the size and boundaries of your level, and control the +appearance of the notebook paper background of your level. + +* **Bounded** is the default. The camera won't scroll past the top-left corner + of the page (0,0), and the level size is capped to 2550x3300, or the + approximate size of an 11:9 standard sheet of notebook paper in pixels. +* **No Negative Space** is like Bounded, but the width and height of the level + have no boundary. Levels can grow "infinitely" to the right and downward + but no negative coordinates past the top or left edge. +* **Unbounded** allows for "infinite" sized maps that give unlimited room to + grow your level. The wallpaper on this level type only uses the "tiling" + pattern, so notebook-themed levels won't show the top/left decorations. + +### Wallpaper + +The wallpaper affects the "theme" of your level. Project: Doodle is themed around +hand-drawn mazes on paper, so the built-in themes look like various kinds of +paper. + +* **Notebook** looks like standard ruled notebook paper. It's a white paper with + blue horizontal lines, a single red vertical line down the left, and a wide + margin on the top and left edges. +* **Legal Pad** looks like ruled yellow legal pad. It's similar to Notebook but + has yellow paper and a second vertical red line down the left. +* **Blueprint** is a dark blueprint paper background with a repeating grid pattern. + Notably, the default Color Palette for this theme is different than normal: + "solid" lines are white instead of black, to show up better against the dark + background. + +The decorations of the wallpaper vary based on the Page Type. For example, the +Notebook and Legal Pad have extra padding on the top of the page and red lines +going down just the left side, and the rest of the level uses the repeating blue +lines pattern. The page types and their effect on the wallpapers are: + +* **Bounded** and **No Negative Space** will show the decorations for the top + and left edges of the page, as these levels are bounded on their top/left + corner. +* **Unbounded** levels only use the repeating tiled pattern across the entire + level, because there is no top-left boundary to anchor those decorations to. + +## Editor Mode Interface + +![Level Editor View](../images/editor-1.png) + +Quick 5-minute tour of what you're looking at: + +* The top of the window has your **Menu Bar**: + * **New Level** opens the "Create a New Level" menu. + * **New Doodad** opens the Doodad Editor for drawing a new custom doodad. + You're prompted for the size of the doodad, which will be its width and + height boundary. For example, a size of "100" means a 100x100 pixel graphic + for your custom doodad. + * **Save** and **Save as...** let you save the current Level or Doodad you're + drawing to disk. "Save" will only ask for the filename once whereas "Save as" + asks every time. + * **Load** opens the "Edit a Level" menu to choose a Level or Doodad to edit. + * **Options** options the Level Options dialog so you can modify the page type + and wallpaper setting. +* The panel on the left side of the window is your **Tool Box**. Clicking these + buttons activates a specific drawing tool or mode: + * **Pencil Tool** lets you click, drag, and draw pixels of your selected + Palette color onto your level freehand. + * **Line Tool** lets you easily draw a straight line between two points. Click + in your level where you want the first point to be, and drag your mouse to + the second point. Release the mouse to commit the line to your drawing. + * **Rectangle Tool** lets you easily draw rectangles on your level. + * **Ellipse Tool** lets you draw circles or elliptical shapes. + * **Doodad Tool** lets you drag doodads such as buttons and doors onto your + level. See the [Doodad Tool](#doodad-tool) below. + * **Link Tool** lets you link doodads together so that they can interact off + each other. For example, a Button connected to an Electric Door will cause + the door to open and close when the button is pressed. See [Link Tool](#link-tool) + below. + * **Eraser Tool** cleans up your mistakes. Click and drag over pixels you've + drawn to delete the pixels from your level. + * **Brush Size:** the "Size:" label shows the brush size of your current drawing + tool. This translates to the line thickness, or how big your pixels are when + drawn into the level. Click the + and - buttons to increase or decrease the + brush size, and draw thicker or thinner lines. +* The panel on the right side of the window is your **Palette** of colors to + draw with. + +![Doodad Toolbar View](../images/editor-2.png) diff --git a/dev-assets/guidebook/docs/doodad-tool.md b/dev-assets/guidebook/docs/doodad-tool.md new file mode 100644 index 0000000..02c3ef0 --- /dev/null +++ b/dev-assets/guidebook/docs/doodad-tool.md @@ -0,0 +1,118 @@ +# Doodad Tool + +The game ships with a command-line program called `doodad` which assists in +creating and managing custom doodads and levels. + +The `doodad` tool can show and set details on .doodad and .level files used by +the game, create new doodads from PNG images and attach custom JavaScript source +to program behavior of doodads. + +## Where to Find It + +The `doodad` tool should be in the same place as the game executable. + +On Windows, the program is called `doodad.exe` and comes in the zip file next +to the game executable, `doodle.exe`. + +On Linux, it will typically be at `/opt/project-doodle/doodad`. + +On Mac OS, it is found inside the .app bundle. + +## Usage + +Run `doodad --help` to get usage information. + +The program includes several sub-commands, such as `doodad convert`. Type a +subcommand and `--help` to get help on that command, for example: + +```bash +doodad convert --help +``` + +# Examples + +Here are some common scenarios and use cases for the doodad tool. + +## Show + +```bash +# Usage: +doodad show [doodad or level filename] +``` + +Shows metadata and details about a level or doodad file. + +Examples: + +```bash +$ doodad show button.doodad +===== Doodad: button.doodad ===== +Headers: + File version: 1 + Game version: 0.0.10-alpha + Doodad title: Button + Author: Noah + Locked: true + Hidden: false + Script size: 473 bytes + +Palette: + - Swatch name: Color<#000000+ff> + Attributes: solid + Color: #000000 + - Swatch name: Color<#666666+ff> + Attributes: none + Color: #666666 + - Swatch name: Color<#999999+ff> + Attributes: fire + Color: #999999 + +Layer 0: button1 +Chunks: + Pixels Per Chunk: 37^2 + Number Generated: 1 + Coordinate Range: (0,0) ... (36,36) + World Dimensions: 36x36 + Use -chunks or -verbose to serialize Chunks + +Layer 1: button2 +Chunks: + Pixels Per Chunk: 37^2 + Number Generated: 1 + Coordinate Range: (0,0) ... (36,36) + World Dimensions: 36x36 + Use -chunks or -verbose to serialize Chunks +``` + +## Convert + +```bash +# Usage: +doodad convert [options] +``` + +### Creating a Doodad from PNG images + +Suppose you have PNG images named "frame0.png" through "frame3.png" and want +to create a doodad from those images. This will convert them to the doodad +file "custom.doodad": + +```bash +# Convert PNG images into a doodad. +doodad convert frame0.png frame1.png frame2.png frame3.png custom.doodad + +# The same, but also attach custom tags with the doodad. +doodad convert --tag color=blue frame{0,1,2,3}.png custom.doodad +``` + +### Convert a level to a PNG image + +```bash +doodad convert my.level output.png +``` + +### Create a level from a PNG image + +```bash +doodad convert level.png output.level +``` diff --git a/dev-assets/guidebook/docs/images/editor-1.png b/dev-assets/guidebook/docs/images/editor-1.png new file mode 100644 index 0000000..ff354b8 Binary files /dev/null and b/dev-assets/guidebook/docs/images/editor-1.png differ diff --git a/dev-assets/guidebook/docs/images/editor-2.png b/dev-assets/guidebook/docs/images/editor-2.png new file mode 100644 index 0000000..1c48074 Binary files /dev/null and b/dev-assets/guidebook/docs/images/editor-2.png differ diff --git a/dev-assets/guidebook/docs/images/main-menu.png b/dev-assets/guidebook/docs/images/main-menu.png new file mode 100644 index 0000000..ddd7db1 Binary files /dev/null and b/dev-assets/guidebook/docs/images/main-menu.png differ diff --git a/dev-assets/guidebook/docs/index.md b/dev-assets/guidebook/docs/index.md new file mode 100644 index 0000000..a09f86a --- /dev/null +++ b/dev-assets/guidebook/docs/index.md @@ -0,0 +1,15 @@ +# Welcome to Project: Doodle + +![](images/main-menu.png) + +[Project: Doodle](about.md) is a drawing-based maze game themed around hand-drawn +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, and play it. + +## Table of Contents + +* [Creating Custom Levels](custom-levels/) +* [Creating Custom Doodads](custom-doodads/) + * [Draw Sprites In-Game](custom-doodads/edit-in-game.md) + * [Draw Sprites with an External Program](custom-doodads/edit-external.md) + * [Program Them with JavaScript](custom-doodads/scripts.md) diff --git a/dev-assets/guidebook/mkdocs.yml b/dev-assets/guidebook/mkdocs.yml new file mode 100644 index 0000000..d734914 --- /dev/null +++ b/dev-assets/guidebook/mkdocs.yml @@ -0,0 +1,8 @@ +site_name: "Project: Doodle Guidebook" +nav: + - Home: index.md + - About: about.md + - "Custom Doodads": custom-doodads/ +markdown_extensions: + - toc: + permalink: "#" diff --git a/dev-assets/guidebook/pages/Home.md b/dev-assets/guidebook/pages/Home.md deleted file mode 100644 index c7be728..0000000 --- a/dev-assets/guidebook/pages/Home.md +++ /dev/null @@ -1,9 +0,0 @@ -# Guidebook to {{ app_name }} - -This is the users manual to {{ app_name }}, a drawing-based maze game. - -## Creating Custom Content - -* [Doodad Scripts](DoodadScripts.html) - -v{{ app_version }} diff --git a/dev-assets/guidebook/pages/index.html b/dev-assets/guidebook/pages/index.html deleted file mode 100644 index bb332e4..0000000 --- a/dev-assets/guidebook/pages/index.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - {{ app_name }} Guidebook - - - - - - - - -
-
- -
-
- - - diff --git a/dev-assets/guidebook/pages/markdown.html b/dev-assets/guidebook/pages/markdown.html deleted file mode 100644 index 0ab3a1c..0000000 --- a/dev-assets/guidebook/pages/markdown.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - {{ title }} - - - - - - - -$CONTENT - - - diff --git a/dev-assets/guidebook/pages/res/main.css b/dev-assets/guidebook/pages/res/main.css deleted file mode 100644 index 4aa5246..0000000 --- a/dev-assets/guidebook/pages/res/main.css +++ /dev/null @@ -1,66 +0,0 @@ -body,html { - margin: 0; - padding: 0; - width: 100%; - height: 100%; - overflow: hidden; -} -body { - background-color: #EEE; - font-family: "Trebuchet MS", Arial, Helvetica, sans-serif; - font-size: 16px; - color: #000; - line-height: 1.4em; -} - -div#sidebar { - position: absolute; - top: 0; - left: 0; - bottom: 0; - width: 220px; - background-color: #000066; - color: #EEE; -} - -nav { - padding: 1.5rem; -} - -nav ul { - margin: 0; - padding: 0; - list-style: none; -} -nav ul li { - display: block; -} -nav a:link, nav a:visited { - color: #EEE; - text-decoration: none; -} -nav a:hover, nav a:active { - color: #F9F; - text-decoration: underline; -} - -div#content { - position: absolute; - top: 0; - left: 220px; - right: 0; - bottom: 0; -} - -div#content div { - position: relative; - width: 100%; - height: 100%; -} - -div#content iframe { - width: 100%; - height: 100%; - border: 0; - overflow: auto; -} diff --git a/dev-assets/guidebook/pages/res/markdown.css b/dev-assets/guidebook/pages/res/markdown.css deleted file mode 100644 index 5a193aa..0000000 --- a/dev-assets/guidebook/pages/res/markdown.css +++ /dev/null @@ -1,25 +0,0 @@ -body { - background-color: #EEE; - font-family: "Trebuchet MS", Arial, Helvetica, sans-serif; - font-size: 16px; - color: #000; - line-height: 1.4em; - margin: 2rem; -} - -a:link, a:visited { - color: #006699; - text-decoration: underline; -} -a:hover, a:active { - color: #996600; -} - -.codehilite { - border: 1px solid #222; -} -pre { - font-family: "Lucida Console", "DejaVu LGC Sans Mono", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Ubuntu Mono", monospace; - margin: 0; - padding: 8px; -} diff --git a/dev-assets/guidebook/pages/res/syntax.css b/dev-assets/guidebook/pages/res/syntax.css deleted file mode 100644 index bf82aed..0000000 --- a/dev-assets/guidebook/pages/res/syntax.css +++ /dev/null @@ -1,69 +0,0 @@ -.codehilite .hll { background-color: #ffffcc } -.codehilite { background: #f8f8f8; } -.codehilite .c { color: #408080; font-style: italic } /* Comment */ -.codehilite .err { border: 1px solid #FF0000 } /* Error */ -.codehilite .k { color: #008000; font-weight: bold } /* Keyword */ -.codehilite .o { color: #666666 } /* Operator */ -.codehilite .ch { color: #408080; font-style: italic } /* Comment.Hashbang */ -.codehilite .cm { color: #408080; font-style: italic } /* Comment.Multiline */ -.codehilite .cp { color: #BC7A00 } /* Comment.Preproc */ -.codehilite .cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */ -.codehilite .c1 { color: #408080; font-style: italic } /* Comment.Single */ -.codehilite .cs { color: #408080; font-style: italic } /* Comment.Special */ -.codehilite .gd { color: #A00000 } /* Generic.Deleted */ -.codehilite .ge { font-style: italic } /* Generic.Emph */ -.codehilite .gr { color: #FF0000 } /* Generic.Error */ -.codehilite .gh { color: #000080; font-weight: bold } /* Generic.Heading */ -.codehilite .gi { color: #00A000 } /* Generic.Inserted */ -.codehilite .go { color: #888888 } /* Generic.Output */ -.codehilite .gp { color: #000080; font-weight: bold } /* Generic.Prompt */ -.codehilite .gs { font-weight: bold } /* Generic.Strong */ -.codehilite .gu { color: #800080; font-weight: bold } /* Generic.Subheading */ -.codehilite .gt { color: #0044DD } /* Generic.Traceback */ -.codehilite .kc { color: #008000; font-weight: bold } /* Keyword.Constant */ -.codehilite .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */ -.codehilite .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */ -.codehilite .kp { color: #008000 } /* Keyword.Pseudo */ -.codehilite .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */ -.codehilite .kt { color: #B00040 } /* Keyword.Type */ -.codehilite .m { color: #666666 } /* Literal.Number */ -.codehilite .s { color: #BA2121 } /* Literal.String */ -.codehilite .na { color: #7D9029 } /* Name.Attribute */ -.codehilite .nb { color: #008000 } /* Name.Builtin */ -.codehilite .nc { color: #0000FF; font-weight: bold } /* Name.Class */ -.codehilite .no { color: #880000 } /* Name.Constant */ -.codehilite .nd { color: #AA22FF } /* Name.Decorator */ -.codehilite .ni { color: #999999; font-weight: bold } /* Name.Entity */ -.codehilite .ne { color: #D2413A; font-weight: bold } /* Name.Exception */ -.codehilite .nf { color: #0000FF } /* Name.Function */ -.codehilite .nl { color: #A0A000 } /* Name.Label */ -.codehilite .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */ -.codehilite .nt { color: #008000; font-weight: bold } /* Name.Tag */ -.codehilite .nv { color: #19177C } /* Name.Variable */ -.codehilite .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */ -.codehilite .w { color: #bbbbbb } /* Text.Whitespace */ -.codehilite .mb { color: #666666 } /* Literal.Number.Bin */ -.codehilite .mf { color: #666666 } /* Literal.Number.Float */ -.codehilite .mh { color: #666666 } /* Literal.Number.Hex */ -.codehilite .mi { color: #666666 } /* Literal.Number.Integer */ -.codehilite .mo { color: #666666 } /* Literal.Number.Oct */ -.codehilite .sa { color: #BA2121 } /* Literal.String.Affix */ -.codehilite .sb { color: #BA2121 } /* Literal.String.Backtick */ -.codehilite .sc { color: #BA2121 } /* Literal.String.Char */ -.codehilite .dl { color: #BA2121 } /* Literal.String.Delimiter */ -.codehilite .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */ -.codehilite .s2 { color: #BA2121 } /* Literal.String.Double */ -.codehilite .se { color: #BB6622; font-weight: bold } /* Literal.String.Escape */ -.codehilite .sh { color: #BA2121 } /* Literal.String.Heredoc */ -.codehilite .si { color: #BB6688; font-weight: bold } /* Literal.String.Interpol */ -.codehilite .sx { color: #008000 } /* Literal.String.Other */ -.codehilite .sr { color: #BB6688 } /* Literal.String.Regex */ -.codehilite .s1 { color: #BA2121 } /* Literal.String.Single */ -.codehilite .ss { color: #19177C } /* Literal.String.Symbol */ -.codehilite .bp { color: #008000 } /* Name.Builtin.Pseudo */ -.codehilite .fm { color: #0000FF } /* Name.Function.Magic */ -.codehilite .vc { color: #19177C } /* Name.Variable.Class */ -.codehilite .vg { color: #19177C } /* Name.Variable.Global */ -.codehilite .vi { color: #19177C } /* Name.Variable.Instance */ -.codehilite .vm { color: #19177C } /* Name.Variable.Magic */ -.codehilite .il { color: #666666 } /* Literal.Number.Integer.Long */