Skip to content

Commit 0ae7c78

Browse files
authored
Merge pull request #15 from theprototype-app/docs-36-int-125
[docs] 1.25: panels own the keys, code workspace sidebars, Tidy graph, select inside water, water + fluid fixes, Fluids page; What's new
2 parents d62753e + a0be0e7 commit 0ae7c78

29 files changed

Lines changed: 495 additions & 25 deletions

‎docs/build-a-game.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,9 @@ tune deadzone, sensitivity and invert-Y under **Settings ▸ Input**.
7777
Scrolling changes your speed, and because a controller node is present a **Move Speed**
7878
node can read or set that same value — so a sprint key is just a key press wired into it.
7979

80+
Since 1.25 the controller card also has **code**: double-click it to steer speed, jump height, eye height, gravity or
81+
walk/fly every frame from this player's keys — see [The Player's code](code-workspace.md#the-players-code).
82+
8083
!!! note
8184
Delete the Character Controller node and movement is exactly the default fly again.
8285
The controller adds capability without taking the default away.

‎docs/code-workspace.md‎

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,18 @@ itself as JSON. Each source is a **tab**, and your edits stay in the tab until y
1111
It opens by itself when you ask for code:
1212

1313
- **Edit code** on a Script node, **Code** on a Behaviour node, or a double-click on any node that has code (see
14-
[Open code](main-graph.md#open-code));
14+
[Open code](main-graph.md#open-code)) — since 1.25 that includes a game's [Player](#the-players-code);
1515
- a double-click on a `.js` file in the [Explorer](explorer.md), or right-click it ▸ **Open in code editor**;
1616
- the dock's **+** menu ▸ **Code**, or the optional `{}` toolbar button (add it with *Customize the toolbar*);
1717
- **Graph JSON** in the workspace's header opens the graph the Node editor is showing.
1818

1919
It docks as a tab at the bottom, beside the Node editor and the Explorer, or floats as a window (**⧉** to float,
20-
**⇩ Dock** to put it back).
20+
**⇩ Dock** to put it back). Everything on this page works in both. In a narrow window or on a phone the
21+
[sidebars](#sidebars) open **over** the editor, one at a time (toggle buttons in the header).
22+
23+
When the workspace has the keyboard, it keeps it: <kbd>W</kbd><kbd>A</kbd><kbd>S</kbd><kbd>D</kbd> never fly the camera
24+
from here (see [Keys follow the panel you are in](controls.md#keys-follow-the-panel-you-are-in)). In the undocked
25+
window the tabs sit in the title bar and can be clicked; the title bar around them still drags the window.
2126

2227
## Editing and saving
2328

@@ -32,6 +37,79 @@ running the last good version.
3237

3338
When the code is good, everything that runs it reloads — on every player's screen.
3439

40+
**Unsaved changes are guarded.** Closing a tab with unsaved edits asks first. Closing the whole workspace with unsaved
41+
files asks **Save all / Don't save / Cancel** — a file whose code has an error is not saved, and the dialog says so.
42+
Leaving the page with unsaved code shows the browser's warning.
43+
44+
**Undo and redo** (<kbd>Ctrl</kbd>+<kbd>Z</kbd> / <kbd>Ctrl</kbd>+<kbd>Y</kbd>) step through saved code edits, on every
45+
peer; an open tab follows them.
46+
47+
## Sidebars
48+
49+
![The code workspace in 1.25: Open editors and the Project tree on the left, the tab strip, and the Outline on the right](img/code-workspace/sidebars.png)
50+
51+
### Left: Open editors and Project
52+
53+
<kbd>Ctrl</kbd>+<kbd>B</kbd> shows or hides the left sidebar.
54+
55+
- **Open editors** lists every open tab, in the same order as the tab strip. Drag a row to reorder (the strip follows);
56+
**✕** closes it (unsaved files ask first).
57+
- **Project** lists every script in the scene as a tree, with a search box:
58+
- **Graphs** — per graph (Main first, then each object's), its Script nodes, Behaviour nodes and the
59+
[Player's code](#the-players-code), plus `graph.json` (the whole graph as editable [JSON](#graph-json)).
60+
- **Script files** — the `.js` files in your Library, with how many nodes run each.
61+
- **Module sources** — the module and kit files the game uses, **read-only** (see [Module code](#module-code)).
62+
- The search also matches folder names (*minigolf rules*).
63+
- Drag the line between the two sections to share the height; double-click it to reset. Drag the sidebar's edge to
64+
resize it — the width is remembered.
65+
66+
### Right: Outline, Problems, Bound nodes, Find
67+
68+
<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>B</kbd> shows or hides the right sidebar. It has four tool tabs:
69+
70+
- **Outline** — the active file's params, state, handlers, methods and functions, a script's inputs and returned
71+
outputs, a graph's nodes. Click one to jump to its line.
72+
- **Problems** — syntax errors and lint advice (for example, `Math.random` breaks peer sync) for every open file *as you
73+
type*, plus anything a node reported while running. The tab shows a count; click a problem to jump to it.
74+
- **Bound nodes** — which graph nodes run this file. Click one to select it in the Node editor (entering its group if
75+
it is inside one).
76+
- **Find in files** (<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>F</kbd>) — searches every script in the project, open files'
77+
unsaved text first. Toggles: match case, whole word, regular expression, include module sources. Click a result to
78+
open it at its line.
79+
80+
## Tabs, quick open and the keyboard
81+
82+
- With many tabs the **tab strip** scrolls: the mouse wheel scrolls it sideways and a thin scrollbar shows. The active
83+
tab is always scrolled into view. Drag a tab to reorder it.
84+
- <kbd>Ctrl</kbd>+<kbd>P</kbd> — **quick open**: open any script in the project by typing part of its name (letters in
85+
order: `plwa` finds *Player: walk*). <kbd>↑</kbd>/<kbd>↓</kbd> and <kbd>Enter</kbd>.
86+
- <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>O</kbd> — **go to symbol**: jump to a function, handler, param or state key of
87+
the current file.
88+
- The tab strip, Open editors, the Project tree and the tool tabs are each one <kbd>Tab</kbd> stop. <kbd>←</kbd>/<kbd>→</kbd>
89+
(strip, tools) and <kbd>↑</kbd>/<kbd>↓</kbd> (lists) move, <kbd>←</kbd>/<kbd>→</kbd> in the tree close and open
90+
folders, <kbd>Enter</kbd> opens, <kbd>Delete</kbd> closes a tab.
91+
92+
## The Player's code
93+
94+
Since 1.25 the **Player** card in a game's graph (a *Character Controller*, such as *Player: walk* in Mini Golf, Escape
95+
Room, Sky Run and Towers) opens its code like any other code node: **double-click it**, or right-click ▸ **Open code**.
96+
The code runs every frame on each player's own machine and decides how *that* player moves:
97+
98+
```js
99+
// settings = the card's values { mode, speed, jumpHeight, eyeHeight, gravity }
100+
// input = this player's keys { x, z, jump, sprint (Shift), crouch (Ctrl) }
101+
// time = seconds since Play started
102+
if (input.sprint) return { speed: settings.speed * 1.8 }; // hold Shift to run
103+
return {}; // anything left out keeps the card's value
104+
```
105+
106+
- <kbd>Ctrl</kbd>+<kbd>S</kbd> saves it — checked first (broken code never applies), sent to everyone, one undo step.
107+
- A wrong key or type in what you return shows on the node's red error badge.
108+
- **Engine source** (toolbar) shows the built-in walker code it steers, read-only.
109+
- With no code saved, the Player behaves exactly as before.
110+
111+
![Player: walk open in the code workspace, with Engine source in the toolbar and the Player code row in the Project tree](img/code-workspace/player-code.png)
112+
35113
## Code and files
36114

37115
- **Save as file** turns a node's inline code into a script file in your Explorer and binds the node to it.
@@ -49,6 +127,10 @@ A module's source opens **read-only** (a lock on its tab): it runs the same for
49127
a module binds to its own file offers **Make editable copy**, which copies the code into a script the scene owns and
50128
points the node at it — see [Make editable copy](main-graph.md#make-editable-copy).
51129

130+
A file opened from **Module sources** in the [Project tree](#left-open-editors-and-project) has a copy button (or
131+
**Make editable copy** in the toolbar) that puts a copy in your Library for you to edit. The module keeps running its own
132+
code, so use **Use file…** on a Script node to run your copy.
133+
52134
## Graph JSON
53135

54136
**Graph JSON** opens the graph as JSON. Edit the nodes and edges and press **Apply** (<kbd>Ctrl</kbd>+<kbd>S</kbd>).
@@ -63,6 +145,12 @@ The **Live** checkbox on a node or behaviour tab applies inline edits as you typ
63145

64146
## Limits
65147

148+
- The Player's code can change speed, jump height, eye height, gravity and walk/fly each frame; it cannot replace the
149+
walker itself (collisions, steps) — that is the engine source.
150+
- Other built-in nodes have parameters only (edited in the ⓘ panel); Script, Behaviour, Custom nodes and the Player are
151+
the nodes with code.
152+
- Find in files stops at 400 results.
153+
66154
- A node bound to a file still carries its code, so a scene runs the same whether or not the file is in anyone's
67155
Library.
68156
- Files are addressed by their content: two files with byte-identical content are the same file.

0 commit comments

Comments
 (0)