Reference

Pathlace docs

One language, three views: blocks on a canvas, the text underneath, and a set of edit operations an AI can apply safely.

Programs

A program is a text file ending in .plc. It starts with a version line, may declare types, and has one flow named main.

pathlace 0.1

type Todo = { userId: Int, id: Int, title: Text, completed: Bool }

flow main() -> List<Todo> {
  #1 @n_k3f9 fetch = http.getJson<List<Todo>>(url: "https://jsonplaceholder.typicode.com/todos")
     @n_p2a1 open = list.filter(items: fetch.out, where: item => not item.completed)
     @n_q8z0 first5 = list.take(items: open.out, n: 5)
  #2 @n_m4c7 show = ui.table(rows: first5.out, title: "Open todos")
  return first5.out
}

• #1, #2 mark actions. They run in that order and are the only blocks allowed to have effects (fetch, show, save). An action may only read earlier actions.
• A line without a number is pure. It runs when something downstream needs it and may be re-evaluated freely.
• @n_k3f9 is the block's permanent id. Wires reference ids, so labels are display only and renaming never breaks anything.
• label = kind(arg: value, ...) calls a block. Arguments are always named. Read a block's result with label.out.
• return is the program's value: what the CLI prints and what a webhook responds with.

Types

Built-in: Int, Float, Text, Bool, Json, List<T>. Declare records with type Name = { field: Type, ... }. Generic blocks such as http.getJson<T> check external data against T at the boundary and report the path of any mismatch, so nothing downstream sees a bad shape.

Expressions

Arguments take expressions: literals (5, 1.5, "text", true), references (name.out), field access (item.completed), arithmetic and comparison (+ - * / == != < > <= >=), and, or, not, list literals ([a.out, b.out]) and one-parameter lambdas for blocks that take them (item => not item.completed).

Two deliberate limits keep the canvas honest: blocks are only called at the top level of a flow, never nested inside an expression, and there is no if-expression. Use the pick block.

Files and layout

Box positions live in name.plc.layout.json, keyed by block id. Custom blocks live in blocks.js next to the program. Neither is part of the program text, so moving a box or adding a block definition never shows up as a program change.

Blocks

277 built-in blocks, generated from spec/stdlib.json. A action badge means the block has an effect and must be numbered.

GUI

Widgets that draw in the preview and return their current value. Each is an action because it shows something.

2D

Shapes are plain values; canvas2d.show paints a list of them. In the Game section this runs every frame.

3D

Meshes are plain values; scene3d.show renders them with three.js and a slowly orbiting camera.

Game loop

Time, input and state that carries over between frames.

Physics

A body is { x, y, w, h, vx, vy }. Apply gravity, walk, jump and step it against walls each frame; the results are plain values you draw with physics.toRect or toSprite.

Tilemaps

Levels as rows of characters. tilemap.walls feeds physics.step, tilemap.draw and tilemap.sprites make shapes, tilemap.find places things.

Sound

Tones from note names, short beeps on events, melodies, and sound files from your uploaded assets. Silent in the CLI and in webhooks.

Web

Fetch JSON or text from any URL, or post data to one. These work in every edition and in the cloud.

Data and JSON

Read, build and reshape records. Everything here is a pure value block.

Text

Join, split, search, format and convert text.

Math and random

Arithmetic, trigonometry, interpolation and random numbers, picks and ids.

Lists

Filter, map, sort, group and summarise lists. The where, sortBy and pluck blocks need no lambda.

Logic and compare

Booleans, comparisons, conditional picks and conversions between value types.

Time

Now, parts, formatting and arithmetic on dates.

Color

Build colours from RGB or HSL, mix them, or pick at random. Results are CSS colour strings for 2D and 3D blocks.

Cloud

Pathlace Cloud, the free key-value store and webhook runner. Spaces are public by name.

AI

Ask a model from inside a program. The fixture host returns a mock reply.

Cloud HTTP API

Base URL: https://olejisysfdhfjybefvbm.supabase.co/functions/v1/pathlace-api. Everything is JSON. Routes marked account take the session token from sign-in as Authorization: Bearer; the rest are open. Spaces and keys are names matching [a-zA-Z0-9][a-zA-Z0-9_.:-]{0,79}.

Who may do what

• Reading a space needs no account while the space is public (the default). The owner can make a space private, after which only the owner's token reads it.
• Writing always needs an account. The first write to a new space name claims it for that account; from then on only the owner can write or delete there, and anyone else gets a 403 with a hint to pick another name.
• Webhooks belong to the account that published them and run as that account, so a hook can write to its owner's spaces even when the caller is anonymous. That is how an exported game keeps a shared high score: the game posts to the hook, the hook does the write.
• Deleting an account removes its programs, spaces (with every key) and webhooks.

Daily limits

Per account and day: 2000 webhook runs, 5000 data writes, 50 Lacey messages, 100 file uploads, 10 emails. Over the limit the API answers 429 with a plain message; counters reset at midnight UTC. Sign-in attempts are also throttled per address.

Public spaces are readable by anyone who knows the name, so keep secrets out of them or switch the space to private on your account page.

Sharing programs

Any program saved to the cloud can get a public link. In Studio: Account → Share link, add a one-line description, press Create share link. The link looks like https://pathlace.com/p/p_1a2b3c4d5e and opens a page with three tabs: App runs the program once and reruns it when a widget changes, Game runs it every frame with the keyboard and pointer live, and Code shows the program text with a copy button. Open in Studio loads a fresh copy into the visitor's own Studio (/app/?open=p_…), so remixing never touches your original. Shared programs also appear in the gallery. Turn sharing off from the same dialog or on the account page and the link stops working at once.

Shared programs run in the visitor's browser on sample data, and cloud blocks read public spaces only. Anything secret should stay out of a shared program: the text is public.

Images and sounds

Account → Images and sounds (or the account page) uploads PNG, JPEG, GIF, WebP, SVG, MP3, WAV and OGG files to your account. Each file gets a public URL. Paste it into canvas2d.image to draw a picture, or into sound.play to play a clip. Tones need no files: sound.tone and sound.beep play notes by name (C4, F#5) or frequency, sound.melody plays a list of notes, and sound.playWhen fires once each time a condition becomes true, which is how a paddle game goes blip. Sound blocks are silent on the command line and in webhooks.

Webhooks

In the desktop app, sign in, then choose File, then Publish as webhook. Studio posts the program text with your token and shows the hook URL. Any HTTP client can then run it:

curl -X POST https://olejisysfdhfjybefvbm.supabase.co/functions/v1/pathlace-api/hook/h_xxxxxxxx \
  -H 'content-type: application/json' \
  -d '{ "name": "Bob" }'

Inside the program, webhook.payload returns the posted JSON and webhook.field picks one value out of it. The response includes the return value, every view the program showed and every log line. The hook runs as you: its cloud.put blocks write to your spaces. Manage and delete hooks from Account → Data and webhooks in Studio or on the account page.

Two things keep a hook safe once it is public. A secret (Add secret, in the same list) means callers must send the x-pathlace-secret header or the hook refuses to run; rotate or remove it any time. The runs log shows the last 50 calls with timing and any error, so you can see who is hitting it and why it failed.

Accounts

Studio runs programs without an account, and public data reads work for everyone. Storing anything (saving programs to the cloud, writing data spaces, publishing webhooks) needs a free account: press Sign in at the right of the toolbar and create one with an email address and a password, or do the same on the account page of this site. Google sign-in appears as a second option when it is configured.

Once signed in, the account menu gains Save to cloud (Ctrl Shift S), Save a copy, Open from cloud, Share link, Images and sounds and Data and webhooks, and a cloud mark appears next to the program name. Forgot your password? Type your email in the sign-in form and press Forgot password: a reset link arrives by mail when email is switched on; otherwise write to help@pathlace.com. New accounts get a verification mail too; nothing is locked behind it, it just marks the address as yours. Saved programs are private to your account. Pathlace stores your email, name and a salted password hash plus the programs, spaces and webhooks you create, nothing else; Sign out forgets the session on that computer and Delete account removes everything.

Exported apps and games run as whoever opens them, which is usually nobody signed in. Reads of public spaces work; for writes, publish a webhook that does the writing and call it from the exported program with http.postJson.

Adding blocks

Adding works the way it does in Unreal Blueprint. Right-click (or double-click, or long-press on a phone) any empty spot on the canvas and a searchable menu opens there; pick a block and it lands under the cursor. Drag a wire off a port and drop it on empty canvas and the same menu opens context sensitive: from an output it lists only blocks with an input that takes that type and wires the new block in; from an input it lists blocks whose output fits. Type a few letters to filter (gjs finds http.getJson), use the arrow keys, press Enter to add, Esc to close. The Add block button in the toolbar opens the same menu in the middle of the canvas.

Export and compile

A finished program can leave Studio in three shapes. Web page: File → Export → Save .html writes one file with the Pathlace Player (the runtime) and your program inside; open it in any browser, host it on any site, or send it to a friend. Runnable app (desktop Studio only): pick Windows, Linux or macOS and Studio downloads the prebuilt Player for that platform once, glues your program to it and saves a real executable (.exe, a Linux binary, or a zipped .app) that opens straight into your app or game. Source files: the .plc text, its layout and blocks.js.

The export dialog asks how the program runs: App runs once and again whenever a widget changes; Game runs every frame with the keyboard and pointer available; Auto picks Game when the program draws or reads input. Programs built on sample data ship the recorded responses they use, so they still work offline.

The command line does the same without Studio:

plc build game.plc -o game.html
plc pack game.plc --target windows-x64 -o Game.exe
plc pack game.plc --target macos-aarch64 -o Game.app.zip   # also linux-x64, macos-x64

Exported apps are not code-signed. Windows SmartScreen and macOS Gatekeeper will ask before the first launch (macOS: right-click → Open). Custom blocks from blocks.js are included in the export.

Editions

The desktop app (macOS, Windows, Linux) is the full product. The browser edition is deliberately smaller: it runs programs on recorded sample data only, cannot open or save files, shows the block catalog instead of the custom block editor, exports web pages but not runnable apps, and leaves out webhook publishing. Accounts, cloud saves, sharing, data spaces and Lacey work in both. Everything else, including the game loop and 3D, is the same code.

Your own blocks

In Code, the Outside tab is where you extend the language. Write JavaScript, press Load blocks, and the new kinds join the palette under Your blocks.

defineBlock({
  kind: 'my.double',
  doc: 'Twice the number.',
  args: [{ name: 'x', type: 'Float' }],
  out: 'Float',
  run: ({ x }) => x * 2,
});

Types are the same as the language's. Set effect: true for a block that does something, and it becomes an action like any built-in.

Lacey

Lacey is the helper built into the Code section. Sign in, open the Lacey tab, and ask in plain words: add a counter that goes up when I press a button, make the ball bounce, explain this program. She answers in a sentence or two and, when she wants to change something, proposes new program text. The Studio parses and checks the proposal before you see it, shows the difference line by line, and changes nothing until you press Apply this change. Your program text and message are sent to Pathlace Cloud only when you press Send. 50 messages a day per account.

Under the chat, Developer tools exposes the structured edit operations (add_node, set_arg, connect, rename, remove_node) against a known program version. A batch is checked as a whole; if any step fails, nothing changes. Dry run shows the diff first. The schema is in spec/lacey-tools.json.

Signing and trust

Pathlace Studio installers and exported apps are not code-signed yet. On Windows, SmartScreen shows More info → Run anyway the first time; on macOS, right-click the app and choose Open once. The release workflow is ready to sign as soon as certificates are added (docs/signing.md in the source lists exactly what), and every download comes with a SHA256SUMS.txt you can check.