Update documentation

docs/custom-doodads/scripts.md

@@ -473,6 +473,8 @@ their custom event names.
 |------|-----------|--------------|
 | power | boolean | Communicates a "powered" (true) or "not powered" state, as in a Button to an Electric Door. |
 | broadcast:state-change | boolean | An "ON/OFF" button was hit and all state blocks should flip. |
+| 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. |
+| switch:toggle | boolean | A switch has been toggled from on to off. |
 
 ### Message.Publish(name string, data...)
 

docs/doodads.md

@@ -9,11 +9,14 @@ Doodads are available in the Level Editor by clicking on the
 and then dragging a doodad onto your level. See the [Doodad Tool](custom-levels/index.md#doodad-tool)
 for more information.
 
+**See also:** [Linked Doodads](linked-doodads.md) for how doodads interact when
+linked together in your levels.
+
 * [Flags](#flags)
     * [Start Flag](#start-flag)
     * [Exit Flag](#exit-flag)
 * [Doors & Trapdoors](#doors-trapdoors)
-    * [Locked Doors & Keys](#locked-doors-keys)
+    * [Colored Locked Doors & Keys](#colored-locked-doors-keys)
     * [Small Key Doors](#small-key-doors)
     * [Warp Doors](#warp-doors)
     * [Trapdoors](#trapdoors)
@@ -33,9 +36,9 @@ for more information.
 
 ---
 
-# Flags
+## Flags
 
-## Start Flag
+### Start Flag
 
 ![Start Flag](images/doodads/start-flag.png)
 
@@ -49,7 +52,7 @@ A level without a Start Flag will spawn the player at the 0,0 coordinate at
 the top-left corner of the level, and flash an error about the missing Start
 Flag.
 
-## Exit Flag
+### Exit Flag
 
 ![Exit Flag](images/doodads/exit-flag.png)
 
@@ -58,9 +61,9 @@ flag to win the level.
 
 ---
 
-# Doors & Trapdoors
+## Doors & Trapdoors
 
-## Locked Doors & Keys
+### Colored Locked Doors & Keys
 
 ![Blue Locked Door](images/doodads/blue-door.gif) ![Blue Key](images/doodads/blue-key.png)
 
@@ -88,7 +91,7 @@ Each key/door pair also has a distinct shape for color-impaired players:
 * **Yellow Key** (star)
 * **Blue Key** (diamond)
 
-## Small Key Doors
+### Small Key Doors
 
 ![Small Key Door](images/doodads/small-key-door.gif) ![Small Key](images/doodads/small-key.png)
 
@@ -99,7 +102,7 @@ unlock as many Small Key Doors as the number of keys they hold.
 The Small Key Door is permanently unlocked after unlocking it once. A golden
 padlock appears on the door when it's locked, which disappears after unlocking.
 
-## Warp Doors
+### Warp Doors
 
 ![Warp Door](images/doodads/warp-door.gif)
 
@@ -118,7 +121,7 @@ that the door is "locked" and it can not be entered by the player.
 **See also:** the [Blue & Orange Warp Doors](#blue-orange-warp-doors) tied to the
 [State Blocks](#state-blocks).
 
-## Trapdoors
+### Trapdoors
 
 ![Trapdoor](images/doodads/trapdoor-down.gif)
 
@@ -132,7 +135,7 @@ as a solid wall. If the door is open you may run in from the wrong side.
 Trapdoors come in four variants: downward-facing (default), rightward, leftward
 and upwards.
 
-## Crumbly Floor
+### Crumbly Floor
 
 ![Crumbly Floor](images/doodads/crumbly-floor.gif)
 
@@ -145,7 +148,7 @@ of the doodad.
 
 ---
 
-# Gizmos
+## Gizmos
 
 The gizmo doodads work best when **Linked** to other doodads in your level. For
 example, a Button linked to an Electric Door will cause the door to open whenever
@@ -153,7 +156,7 @@ the button is pressed.
 
 **See also:** [Link Tool](custom-levels/index.md#link-tool)
 
-## Buttons
+### Buttons
 
 ![Button Type A](images/doodads/button-a.gif) ![Button Type B](images/doodads/button-b.gif)
 
@@ -169,7 +172,7 @@ Buttons come in two varieties which are cosmetic only:
 * **Button:** a button with a grey arrow that pops back up when pressed.
 * **Button Type B:** a variation without the grey arrow but behaves the same.
 
-## Sticky Button
+### Sticky Button
 
 ![Sticky Button](images/doodads/sticky-button.gif)
 
@@ -180,7 +183,7 @@ When the Sticky Button is pressed, it will emit a `power: on` signal and it will
 signal from another linked doodad, then it will pop back up and can be pressed
 again.
 
-## Switches
+### Switches
 
 ![Switch](images/doodads/switch.gif) ![Switch Right](images/doodads/switch-right.gif)
 
@@ -195,7 +198,7 @@ same way):
 * Side-profile switches to attach to the side of a wall (left and right).
 * Side-profile floor switch.
 
-## Electric Door
+### Electric Door
 
 ![Electric Door](images/doodads/electric-door.gif)
 
@@ -208,13 +211,13 @@ will close.
 
 ---
 
-# Boolean State Doodads
+## Boolean State Doodads
 
 The **Boolean State Doodads** are a series of doodads which have a mutually
 exclusive state from one another, with their state toggled by the "ON/OFF"
 State Button.
 
-## State Button
+### State Button
 
 ![Blue "On"](images/doodads/blue-button.png) ![Orange "Off"](images/doodads/orange-button.png)
 
@@ -232,7 +235,7 @@ its state.
 * When the button is **OFF**, all **blue** state doodads are active. This is the default state.
 * When the button is **ON**, all **orange** state doodads are active.
 
-## State Blocks
+### State Blocks
 
 ![Blue "On"](images/doodads/blue-on.png) ![Blue "Off"](images/doodads/blue-off.png)
 
@@ -244,7 +247,7 @@ another. In one state the block is solid, in another it is passable.
 The ON/OFF block will toggle all state blocks on the level to their opposite
 setting whenever it's touched by the player or other mobile doodad.
 
-## Blue & Orange Warp Doors
+### Blue & Orange Warp Doors
 
 ![Blue Warp Door](images/doodads/warp-door-blue.gif) ![Blue "Off" Door](images/doodads/warp-blue-off.png)
 
@@ -263,22 +266,26 @@ and vice versa for the **Orange Warp Door.**
 
 # Creatures
 
-## Red Bird
+### Red Bird
 
 ![Bird](images/doodads/bird.gif)
 
 The **Bird** is a simple creature which flies left and right across your level,
 changing direction when it encounters an obstacle.
 
+The bird has solid collision on its top side, so the player can ride on it
+across the level. It's very slippery, though!
+
 In the future, the bird will dive-bomb the player character in a diagonal
 trajectory when it sees a shot it can take. This will harm the player if the
 bird hits. If the bird hits the player, or misses and touches the ground, it
 will fly back up to its original altitude and continue its A.I. program of
-flying back and forth and searching for the player.
+flying back and forth and searching for the player. It will also be easier to
+ride more reliably.
 
 Currently, however, the bird is harmless and does not dive bomb the player.
 
-## Red Azulian (Test Mob)
+### Red Azulian (Test Mob)
 
 ![Red Azulian](images/doodads/red-azulian.gif)
 

docs/index.md

@@ -13,6 +13,7 @@ levels with others.
 * [Gameplay Controls](controls.md)
 * [Creating Custom Levels](custom-levels/index.md)
 * [The Built-in Doodads](doodads.md)
+* [Linked Doodads](linked-doodads.md)
 * [Creating Custom Doodads](custom-doodads/index.md)
     * [Draw Sprites In-Game](custom-doodads/edit-in-game.md)
     * [Draw Sprites with an External Program](custom-doodads/edit-external.md)

docs/linked-doodads.md

@@ -0,0 +1,130 @@
+# Linked Doodads
+
+[Doodads](doodads.md) such as Buttons and Switches know how to open Electric Doors via a process known as **linking.** A pair of linked doodads are able to exchange messages with one another, to inform their linked partner about events happening to itself. For example, when the Button is pressed in by the player, it sends a "power" signal to a linked Electric Door to tell it to open. When the button is released, it tells the linked door that power is gone, and the door closes.
+
+## How to Link Doodads
+
+![Link Tool](images/link-tool.png)
+
+In the [Level Editor](custom-levels/index.md), click on the <img src="images/sprites/actor-tool.png" width="16" height="16"> **Doodad Tool** and drag a two doodads into your level, such as a Button and an Electric Door.
+
+Then, select the <img src="images/sprites/link-tool.png" width="16" height="16"> **Link Tool**. When you mouse over the actors, a pink border appears instead of the usual orange.
+
+Click one of the doodads, and then the other doodad. The first doodad will have a solid pink background while awaiting your click on the doodad to link it to. A glowing pink line will now be drawn connecting the two doodads.
+
+You may use the <img src="images/sprites/actor-tool.png" width="16" height="16"> **Doodad Tool** to move the doodads to other places on your level, and they'll remain linked.
+
+Currently, the only way to _unlink_ two doodads is to delete one of them. With the **Doodad Tool**, right-click on a doodad to remove it from your level, or drag it back into the Doodads window.
+
+## Doodad Interactions
+
+This section describes how the built-in doodads interact with one another when they're linked, and some example use cases. Custom doodads made by users should follow similar patterns; check the [PubSub event types](custom-doodads/scripts.md#official-standard-pub-sub-messages) used by built-in doodads, or invent your own custom event types!
+
+### Buttons
+
+Quick reference:
+
+* When linked with an **[Electric Door](#electric-door)**: opens the door while the button is pressed.
+* When linked with a **[Sticky Button](#sticky-button)**: when the button emits power to a pressed Sticky Button, the sticky button pops back up.
+
+Technical details on what PubSub messages the Buttons subscribe to:
+
+* When a mobile doodad touches the button, it presses down and publishes a **power** (true) message. Most doodads interpret this to be a power source, and a true power will make [Electric Doors](#electric-door) open.
+* When the button stops being collided with, it pops back up and publishes a **power** (false) message. This will generally make doodads power down and the Electric Door closes.
+* When the button _receives_ a **sticky:down** (true) event from a linked [Sticky Button](#sticky-button), the Button too presses in and remains pressed in solidarity with the Sticky Button.
+
+### Sticky Button
+
+The Sticky Button is just like the Buttons except it stays pressed forever once touched by the player or other mobile doodad. It emits a **power** (true) button when pressed, as Buttons do, but does not pop back up again.
+
+Sticky Button specific interactions:
+
+* When linked to **[Buttons](#buttons)**: when the Sticky Button is pressed down it will also tell all linked buttons to press down as well, making them all behave as sticky buttons and remain pressed forever.
+* When linked to other **Sticky Buttons**: the buttons will mutually exclusively pop each other's buttons back up when pressed, by emitting power signals to the linked buttons.
+
+When a pressed Sticky Button receives a **power** (true) signal, it pops up back up. This means that if a Sticky Button is linked to another Sticky Button, they would mutually exclusively pop each other's buttons back up when pressed.
+
+### Switches
+
+The various on/off switches emit power signals to linked doodads.
+
+* When linked to an **[Electric Door](#electric-door)**: it will always toggle the door's state, opening if it was closed and vice versa, regardless of the on/off value of the Switch.
+* When linked to a **[Sticky Button](#sticky-button)**: if the Sticky Button were pressed in, it will pop back up.
+* When linked to **[Buttons](#buttons)** or other **Switches**: the Switch will sync its power state to any linked power source that sends a new state.
+
+The technicals:
+
+* When the switch is touched by the player or a mobile doodad, it sends two PubSub messages to linked doodads:
+    * **switch:toggle** (bool), sending the switch's own value (true="on", false="off")
+    * **power** (bool), sending the switch's "on" vs. "off" state.
+* The **power** signals work how you'd expect; they would open or close doors, pop up sticky buttons, etc.
+* The **switch:toggle** though is emitted _just before_ power, so sensitive doodads can behave more smartly to the toggle nature of switches regardless of the on/off state. See [Electric Door](#electric-door).
+* When the **power** signal is _received_ by the Switch, for example because a linked Button was pressed, the Switch will set its power state to match the sender's.
+
+### Electric Door
+
+The Electric Door can only be opened by being powered by a linked doodad, such as a Button or a Switch that emits a **power** event.
+
+Quick reference:
+
+* When linked with **[Buttons](#buttons)**: when the Button is pressed, the door opens; when the button is released, the door shuts.
+* When linked with **[Sticky Buttons](#sticky-buttons)**: same as with Buttons.
+* When linked with **[Switches](#switches)**: the Electric Door will always _toggle_ its state regardless of the power value from the switch. If the door is opened, it will close, and vice versa.
+
+The technicals:
+
+* When the Electric Door receives the **switch:toggle** signal from [Switches](#switches):
+    * It will ignore the _immediately following_ **power** signal, as this will be sent from the Switch immediately following the toggle.
+    * Instead of following the power signal as normal, the door will always just toggle its state to its opposite.
+* When the Electric Door receives the **power** signal from any linked doodad.
+    * If the sender is saying **power** (true), the door will open.
+    * If the sender is saying **power** (false), the door will close.
+    * If the sender is a Switch, this message is ignored in favor of the toggle behavior.
+
+### Warp Doors
+
+Warp Doors let the player fast travel across the map by sending them to a linked Warp Door.
+
+Quick reference:
+
+* When not linked to another door: the door will be "locked" and can not be opened by the player.
+* When linked to one other **Warp Door** of any kind: the Player will open this Warp Door and come out the linked door.
+* When linked to **multiple Warp Doors**, the Player will exit one of them non-deterministically (undefined behavior currently).
+* When linked to a **Warp Door (Blue)** or **Warp Door (Orange)**: the player will always exit from the other door, even if the door is not active. This can be used to create one-way doors.
+
+The technicals (useful if you want to create your own custom warp doors):
+
+* When the player actives the door with the Space key or similar:
+    * If there is no linked door, flash "This door is locked." on screen.
+    * Animate: freeze the player, open the door, hide the player, shut the door.
+    * Publish a **warp-door:incoming** (Actor) event to the linked door so it can receive the actor (player character).
+    * Pre-emptively move the (hidden) player to the X,Y position of the linked door on the level.
+* When a door receives the **warp-door:incoming** event from a linked door:
+    * Unfreeze the incoming actor (the player character)
+    * Animate: open the door, make the player visible, shut the door.
+* Only the Player character can open warp doors, not other mobile doodads.
+* Blue and Orange doors listen for the **broadcast:state-change** event from [State Buttons](#boolean-state-doodads).
+
+### Boolean State Doodads
+
+The blue/orange "ON/OFF" button that toggles boolean state doodads globally across your level.
+
+**State Doodads do NOT need to be linked to one another.** They all automatically communicate with each other globally on your level. The following doodads are State Doodads and do **NOT** need to be linked:
+
+* State Button (the ON/OFF block)
+* Blue and Orange State Blocks
+* Warp Door (Blue)
+* Warp Door (Orange)
+
+Toggling the State Button will globally swap the "solid/invisible" states of the blue and orange doodads to their opposite settings.
+
+The technicals:
+
+* All State Doodads are in the OFF / false state to begin with.
+* When a **State Block** is hit by the player:
+    * It toggles its current state (doodad-local), from OFF to ON.
+    * It emits a broadcast PubSub message **broadcast:state-change** sending its new state.
+* The **State Block** also subscribes to the **broadcast:state-change** channel. So, when a different State Block is toggled by the player, _all_ State Blocks toggle and keep in sync.
+* The various State Doodads listen for the **broadcast:state-change** event and enable or disable themselves accordingly:
+    * In the default OFF state, Blue doodads are active and Orange are inactive.
+    * In the ON state, Orange doodads are active and Blue are inactive.

mkdocs.yml

@@ -6,7 +6,8 @@ nav:
   - Controls: controls.md
   - "Creating Levels": custom-levels/index.md
   - "Built-in Doodads": doodads.md
-  - "Creating Doodads": custom-doodads/index.md
+  - "Linked Doodads": linked-doodads.md
+  - "Creating Custom Doodads": custom-doodads/index.md
   - "Drawing Doodads": custom-doodads/edit-in-game.md
   - "Doodad Scripts": custom-doodads/scripts.md
   - "Shortcut Keys": hotkeys.md