plainscript-lang 1.0.36 → 1.0.361
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +251 -19
- package/compiler/bundler.js +4 -4
- package/compiler/cli.js +18 -18
- package/compiler/dependency-detector.js +34 -22
- package/compiler/generator.js +286 -186
- package/compiler/lexer.js +49 -39
- package/compiler/parser.js +552 -181
- package/compiler/sourcemap.js +1 -1
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +2 -2
- package/docs/FB-PROMPT.md +524 -0
- package/docs/GAME-PROMPT.md +56 -55
- package/docs/PLAINSCRIPT-SPEC.md +16 -15
- package/docs/index.html +13 -6
- package/docs/website/script.js +1 -1
- package/docs/website/style.css +3 -3
- package/examples/ai-providers.pln +1 -1
- package/examples/arrays.pln +1 -1
- package/examples/async-errors.pln +2 -1
- package/examples/auth-api.pln +1 -1
- package/examples/auth-sessions.pln +1 -1
- package/examples/basics.pln +1 -1
- package/examples/bots.pln +1 -1
- package/examples/browser-interactive/README.md +3 -3
- package/examples/browser-interactive/src/interactive.pln +1 -1
- package/examples/cache-and-jobs.pln +1 -1
- package/examples/cache-schedule.pln +1 -1
- package/examples/canvas-game/README.md +4 -4
- package/examples/canvas-game/src/game.pln +1 -1
- package/examples/collections.pln +1 -1
- package/examples/concurrency.pln +1 -1
- package/examples/conditions.pln +1 -1
- package/examples/database.pln +1 -1
- package/examples/day2.pln +1 -1
- package/examples/day3.pln +1 -1
- package/examples/deployment.pln +1 -1
- package/examples/email-send.pln +1 -1
- package/examples/error-handling.pln +3 -2
- package/examples/expressions.pln +1 -1
- package/examples/file-uploads.pln +1 -1
- package/examples/files-and-config.pln +1 -1
- package/examples/files.pln +1 -1
- package/examples/football-backend/app.pln +1 -1
- package/examples/functions.pln +1 -1
- package/examples/hello.pln +1 -1
- package/examples/http-client.pln +1 -1
- package/examples/http.pln +1 -1
- package/examples/id-verification/app.pln +1 -1
- package/examples/javascript-library/README.md +6 -6
- package/examples/javascript-library/public/index.html +1 -1
- package/examples/javascript-library/src/interop.pln +1 -1
- package/examples/json.pln +1 -1
- package/examples/loops.pln +1 -1
- package/examples/modules/app.pln +1 -1
- package/examples/modules/main.pln +1 -1
- package/examples/modules/math.pln +1 -1
- package/examples/mongo.pln +1 -1
- package/examples/objects.pln +1 -1
- package/examples/ocr.pln +1 -1
- package/examples/packages.pln +1 -1
- package/examples/record-kinds.pln +1 -1
- package/examples/records.pln +1 -1
- package/examples/rest-api-fetch.pln +1 -1
- package/examples/rest-api.pln +1 -1
- package/examples/scheduled-tasks.pln +1 -1
- package/examples/search-and-filter.pln +1 -1
- package/examples/server.pln +1 -1
- package/examples/sessions-and-cookies.pln +1 -1
- package/examples/sqlite.pln +1 -1
- package/examples/start.pln +1 -1
- package/examples/stdlib.pln +1 -1
- package/examples/string-verbs.pln +1 -1
- package/examples/telegram-ai-bot.pln +1 -1
- package/examples/telegram-bot.pln +1 -1
- package/examples/testing.pln +1 -1
- package/examples/three-dimensional/README.md +2 -2
- package/examples/three-dimensional/src/scene.pln +1 -1
- package/examples/web-api.pln +1 -1
- package/examples/web-app.pln +1 -1
- package/examples/websocket-server.pln +1 -1
- package/examples/websocket.pln +1 -1
- package/examples/whatsapp-bot/pairing.pln +2 -2
- package/examples/whatsapp-bot/qr.pln +2 -2
- package/package.json +7 -9
package/docs/GAME-PROMPT.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# PlainScript Game Development Prompt Guide (v1.0.
|
|
1
|
+
# PlainScript Game Development Prompt Guide (v1.0.361)
|
|
2
2
|
|
|
3
3
|
The standing instruction sheet for AI agents asked to build games and
|
|
4
4
|
interactive browser apps in PlainScript.
|
|
@@ -11,25 +11,25 @@ the compiler actually implements.
|
|
|
11
11
|
|
|
12
12
|
- **Work in PlainScript.** Write `.pln`, compile it, ship the generated JS. Do
|
|
13
13
|
not hand-rewrite the logic in JavaScript.
|
|
14
|
-
- **Rule Zero
|
|
14
|
+
- **Rule Zero - trust the compiler, nothing else.** Before you claim anything
|
|
15
15
|
works, run `node compiler/cli.js check <file.pln>` (or `plainscript check`).
|
|
16
16
|
If it does not compile, it does not work.
|
|
17
|
-
- **You may import and CALL any JavaScript library**
|
|
17
|
+
- **You may import and CALL any JavaScript library** - canvas, Web Audio,
|
|
18
18
|
three.js, matter.js, npm packages, browser globals. `new Type(args)`, member
|
|
19
19
|
chains, property assignment, promises, and callbacks all work.
|
|
20
20
|
- **Never rewrite PlainScript project logic in JavaScript** just because the
|
|
21
21
|
underlying API is JS. A library is *called* from PlainScript; game logic
|
|
22
22
|
stays in `.pln`. JS is the guest library, not the host language.
|
|
23
23
|
|
|
24
|
-
Every PlainScript block you show a user must compile
|
|
24
|
+
Every PlainScript block you show a user must compile - check it first.
|
|
25
25
|
|
|
26
26
|
---
|
|
27
27
|
|
|
28
28
|
## 1. Philosophy: intent-first, never rewrite in JavaScript (cardinal rule)
|
|
29
29
|
|
|
30
30
|
PlainScript is intent-oriented: you describe *what* the game should do and the
|
|
31
|
-
compiler generates JavaScript. One hard rule
|
|
32
|
-
PlainScript**. v1.0.
|
|
31
|
+
compiler generates JavaScript. One hard rule - **game logic lives in
|
|
32
|
+
PlainScript**. v1.0.361 reaches into any JS API from `.pln`, which makes
|
|
33
33
|
dropping to JS tempting; do not. Every browser capability below stays
|
|
34
34
|
reachable without leaving PlainScript.
|
|
35
35
|
|
|
@@ -58,13 +58,13 @@ my-game/
|
|
|
58
58
|
web app that serves the page; `public/index.html` is a dumb shell owning the
|
|
59
59
|
canvas and script tag; `public/game.js` is build output, never hand-edited;
|
|
60
60
|
`src/*.pln` helpers are pulled in with `bring name from "./helpers.pln"`.
|
|
61
|
-
Keep server and client logic in separate files
|
|
61
|
+
Keep server and client logic in separate files - different runtimes.
|
|
62
62
|
|
|
63
63
|
---
|
|
64
64
|
|
|
65
65
|
## 3. Browser target / how a game is served
|
|
66
66
|
|
|
67
|
-
A game is static files. `server.pln`
|
|
67
|
+
A game is static files. `server.pln` - `serve folder "public"` exposes every
|
|
68
68
|
file under `public/` at `/`, and `reply file` sends the HTML shell for the
|
|
69
69
|
root path:
|
|
70
70
|
|
|
@@ -94,14 +94,14 @@ node compiler/cli.js build src/game.pln -o public/game.js
|
|
|
94
94
|
```
|
|
95
95
|
|
|
96
96
|
**Package-free JS is browser-`<script>`-safe.** Without an npm import the
|
|
97
|
-
generated code has no `require()`
|
|
97
|
+
generated code has no `require()` - it is an async IIFE with a guarded
|
|
98
98
|
`module.exports` tail, so it loads as a plain script.
|
|
99
99
|
|
|
100
100
|
**When you need an npm library in the browser:**
|
|
101
101
|
|
|
102
102
|
1. **CDN global (preferred, stays package-free).** Load the library in
|
|
103
103
|
`index.html` *before* `game.js`; it becomes a browser global that
|
|
104
|
-
PlainScript calls directly
|
|
104
|
+
PlainScript calls directly - no `use`, no bundler:
|
|
105
105
|
|
|
106
106
|
```html
|
|
107
107
|
<script src="https://unpkg.com/three@0.160.0/build/three.min.js"></script>
|
|
@@ -118,7 +118,7 @@ generated code has no `require()` — it is an async IIFE with a guarded
|
|
|
118
118
|
|
|
119
119
|
### 4.1 Canvas 2D
|
|
120
120
|
|
|
121
|
-
Default for 2D games
|
|
121
|
+
Default for 2D games - get the element, its 2D context, draw each frame:
|
|
122
122
|
|
|
123
123
|
```plainscript
|
|
124
124
|
remember canvas as document.getElementById("game")
|
|
@@ -136,8 +136,8 @@ done
|
|
|
136
136
|
requestAnimationFrame(step)
|
|
137
137
|
```
|
|
138
138
|
|
|
139
|
-
Canvas state is property interop
|
|
140
|
-
becomes ...`, `font becomes ...`
|
|
139
|
+
Canvas state is property interop - `fillStyle becomes ...`, `strokeStyle
|
|
140
|
+
becomes ...`, `font becomes ...` - then a draw call. Colors like `"#0d1117"`
|
|
141
141
|
are just strings. Match the canvas backing size to its display size so nothing
|
|
142
142
|
drifts on resize:
|
|
143
143
|
|
|
@@ -180,7 +180,7 @@ remember prog as glProgram(gl, vs, fs)
|
|
|
180
180
|
remember buf as glBuffer(gl, [0.0, 0.0, 1.0, 0.0, 0.0, 1.0])
|
|
181
181
|
```
|
|
182
182
|
|
|
183
|
-
Per-frame render
|
|
183
|
+
Per-frame render - keep setup out of the loop:
|
|
184
184
|
|
|
185
185
|
```plainscript
|
|
186
186
|
make renderTriangle()
|
|
@@ -196,7 +196,7 @@ done
|
|
|
196
196
|
|
|
197
197
|
### 4.3 WebGPU
|
|
198
198
|
|
|
199
|
-
No special syntax
|
|
199
|
+
No special syntax - plain member-chain interop like WebGL, guarded, with the
|
|
200
200
|
promise verbs for async parts. Do not over-promise; support depends on the
|
|
201
201
|
browser/GPU:
|
|
202
202
|
|
|
@@ -237,8 +237,8 @@ done
|
|
|
237
237
|
requestAnimationFrame(loop)
|
|
238
238
|
```
|
|
239
239
|
|
|
240
|
-
v1.0.
|
|
241
|
-
of magic decimals, and a `"#ffffff"` string works too
|
|
240
|
+
v1.0.361 adds hex literals (`0xRRGGBB`): numeric colors use `0xffffff` instead
|
|
241
|
+
of magic decimals, and a `"#ffffff"` string works too - THREE accepts all
|
|
242
242
|
three.
|
|
243
243
|
|
|
244
244
|
---
|
|
@@ -266,7 +266,7 @@ make step(dt)
|
|
|
266
266
|
done
|
|
267
267
|
```
|
|
268
268
|
|
|
269
|
-
- Never mutate world state inside an event handler
|
|
269
|
+
- Never mutate world state inside an event handler - set a flag, let the loop
|
|
270
270
|
consume it.
|
|
271
271
|
- `when <target> "<event>" happens` → `target.addEventListener(event, ...)`
|
|
272
272
|
with the parameter named via `as name` (default `event`).
|
|
@@ -293,7 +293,7 @@ when window "wheel" happens as e
|
|
|
293
293
|
done
|
|
294
294
|
```
|
|
295
295
|
|
|
296
|
-
Touch reuses pointer events (`"touchmove"`)
|
|
296
|
+
Touch reuses pointer events (`"touchmove"`) - call `e.preventDefault()` when
|
|
297
297
|
you own the gesture; `"wheel"` gives `e.deltaY` for zoom; `gamepads()` returns
|
|
298
298
|
connected pads to read inside the loop; drag-and-drop files arrive via
|
|
299
299
|
`droppedFiles(event)` in a `drop` handler.
|
|
@@ -304,9 +304,9 @@ connected pads to read inside the loop; drag-and-drop files arrive via
|
|
|
304
304
|
|
|
305
305
|
The browser runs a single-threaded event loop; the only good loop is
|
|
306
306
|
`requestAnimationFrame` (rAF). A `while true` or long synchronous loop blocks
|
|
307
|
-
rendering, input, and audio
|
|
307
|
+
rendering, input, and audio - the page freezes. Never write one.
|
|
308
308
|
|
|
309
|
-
rAF passes a millisecond timestamp
|
|
309
|
+
rAF passes a millisecond timestamp - difference, normalize to seconds, and
|
|
310
310
|
movement is frame-rate independent:
|
|
311
311
|
|
|
312
312
|
```plainscript
|
|
@@ -324,14 +324,14 @@ requestAnimationFrame(loop)
|
|
|
324
324
|
|
|
325
325
|
Cap `dt` (skip the step after a long stall) so a background-tab resume does not
|
|
326
326
|
jump the sim forward by seconds. For loops that do not need delta time, the
|
|
327
|
-
short form is `every frame ... done` (still rAF under the hood
|
|
327
|
+
short form is `every frame ... done` (still rAF under the hood - see the
|
|
328
328
|
Appendix); use rAF + `dt` when movement must be time-based.
|
|
329
329
|
|
|
330
330
|
---
|
|
331
331
|
|
|
332
332
|
## 7. Asset loading
|
|
333
333
|
|
|
334
|
-
Built-in loaders return promises and **auto-await**
|
|
334
|
+
Built-in loaders return promises and **auto-await** - no `await` written:
|
|
335
335
|
|
|
336
336
|
```plainscript
|
|
337
337
|
remember bg as loadImage("img/background.png")
|
|
@@ -341,16 +341,16 @@ remember manifest as fetchJson("assets/manifest.json")
|
|
|
341
341
|
|
|
342
342
|
- `loadImage(url)` → an `Image` ready for `ctx.drawImage(img, x, y)`.
|
|
343
343
|
- `loadAudio(url)` → an `Audio` element; call `sound.play()`.
|
|
344
|
-
- `fetchJson(url)` → `{ok, status, data, text, parseError}`
|
|
344
|
+
- `fetchJson(url)` → `{ok, status, data, text, parseError}` - never throws on a
|
|
345
345
|
bad status; check `ok`.
|
|
346
346
|
- `fetchBytes(url)` → `{ok, status, data: Uint8Array}` for binary payloads.
|
|
347
347
|
- `readDataUrl(file)` → a `data:` URL string for a `File` (from
|
|
348
|
-
`droppedFiles(event)` or a file input)
|
|
348
|
+
`droppedFiles(event)` or a file input) - feed it straight to `loadImage`.
|
|
349
349
|
|
|
350
350
|
For an `Image` you own, use `new Image()` and `spriteSheet.src becomes "img.png"`.
|
|
351
351
|
|
|
352
352
|
Start the scene **after** assets are ready, or the first frame draws a blank
|
|
353
|
-
flash
|
|
353
|
+
flash - gate scene start on a loaded flag. Sprite atlases are one image plus a
|
|
354
354
|
`fetchJson` manifest of `{x, y, w, h}` frames, drawn with
|
|
355
355
|
`drawImage(sheet, sx, sy, sw, sh, dx, dy, dw, dh)`.
|
|
356
356
|
|
|
@@ -366,7 +366,7 @@ remember sfx as loadAudio("boing.mp3")
|
|
|
366
366
|
|
|
367
367
|
`audioContext()` lazily creates a singleton `AudioContext` (with a
|
|
368
368
|
`webkitAudioContext` fallback); `playTone(freq, seconds, options)` plays a tone
|
|
369
|
-
on it. **Browsers require a user gesture to start audio**
|
|
369
|
+
on it. **Browsers require a user gesture to start audio** - the context stays
|
|
370
370
|
`"suspended"` until a click/keypress/touch, so resume it from the first one:
|
|
371
371
|
|
|
372
372
|
```plainscript
|
|
@@ -376,7 +376,7 @@ done
|
|
|
376
376
|
document.addEventListener("click", resumeAudio)
|
|
377
377
|
```
|
|
378
378
|
|
|
379
|
-
The #1 "audio does not work" bug in browser games
|
|
379
|
+
The #1 "audio does not work" bug in browser games - always wire the resume.
|
|
380
380
|
|
|
381
381
|
---
|
|
382
382
|
|
|
@@ -415,7 +415,7 @@ one predictable place per frame.
|
|
|
415
415
|
|
|
416
416
|
## 10. Collision and physics
|
|
417
417
|
|
|
418
|
-
Two workhorse tests. AABB
|
|
418
|
+
Two workhorse tests. AABB - exact enough for rectangles and tiles:
|
|
419
419
|
|
|
420
420
|
```plainscript
|
|
421
421
|
if enemy.x is at least player.x - 26 and enemy.x is at most player.x + 26 and enemy.y is at least player.y - 26 and enemy.y is at most player.y + 26
|
|
@@ -423,7 +423,7 @@ if enemy.x is at least player.x - 26 and enemy.x is at most player.x + 26 and en
|
|
|
423
423
|
done
|
|
424
424
|
```
|
|
425
425
|
|
|
426
|
-
Circle distance
|
|
426
|
+
Circle distance - compare squared distance against squared radius to skip a
|
|
427
427
|
`Math.sqrt` per pair:
|
|
428
428
|
|
|
429
429
|
```plainscript
|
|
@@ -436,8 +436,8 @@ done
|
|
|
436
436
|
```
|
|
437
437
|
|
|
438
438
|
With many entities, do a broad phase first (bounding boxes, tile-grid buckets)
|
|
439
|
-
and run the precise test only on candidates. When you need real physics
|
|
440
|
-
impulses, joints, continuous collision
|
|
439
|
+
and run the precise test only on candidates. When you need real physics -
|
|
440
|
+
impulses, joints, continuous collision - delegate to a physics library. That is
|
|
441
441
|
interop, not surrender:
|
|
442
442
|
|
|
443
443
|
```plainscript
|
|
@@ -465,7 +465,7 @@ library computes physics.
|
|
|
465
465
|
## 11. UI overlay via DOM
|
|
466
466
|
|
|
467
467
|
Canvas = the world; DOM = the chrome. Score, lives, menus, and buttons live in
|
|
468
|
-
HTML and update by property assignment
|
|
468
|
+
HTML and update by property assignment - `innerHTML becomes`,
|
|
469
469
|
`textContent becomes`, `classList.add`. Do not build UI in canvas when a div
|
|
470
470
|
will do:
|
|
471
471
|
|
|
@@ -529,7 +529,7 @@ compact tick/snapshot; clients render and correct.
|
|
|
529
529
|
|
|
530
530
|
## 13. Persistence
|
|
531
531
|
|
|
532
|
-
`localStorage` is direct interop
|
|
532
|
+
`localStorage` is direct interop - strings only. Wrap state in JSON:
|
|
533
533
|
|
|
534
534
|
```plainscript
|
|
535
535
|
remember rawSave as localStorage.getItem("plainscript-save")
|
|
@@ -540,7 +540,7 @@ done
|
|
|
540
540
|
localStorage.setItem("plainscript-save", jsonEncode(state))
|
|
541
541
|
```
|
|
542
542
|
|
|
543
|
-
Save on meaningful changes or `beforeunload`, not every frame
|
|
543
|
+
Save on meaningful changes or `beforeunload`, not every frame -
|
|
544
544
|
`localStorage` is synchronous and small (~5MB). For structured or large data,
|
|
545
545
|
wrap IndexedDB behind promises via the `idb` npm library (`use idb`).
|
|
546
546
|
|
|
@@ -551,9 +551,9 @@ wrap IndexedDB behind promises via the `idb` npm library (`use idb`).
|
|
|
551
551
|
- **One rAF loop, one `step(dt)`.** No scattered timers drawing or simulating
|
|
552
552
|
independently.
|
|
553
553
|
- **No allocations in the loop.** Reuse typed arrays and mutating math
|
|
554
|
-
(gl-matrix `mat4.rotateX(mat, mat, 0.5)`)
|
|
554
|
+
(gl-matrix `mat4.rotateX(mat, mat, 0.5)`) - never fresh arrays per frame.
|
|
555
555
|
- **Cap dt** so a background-tab resume cannot run the sim forward for seconds.
|
|
556
|
-
- **Canvas sizing discipline.** Match backing size to display size
|
|
556
|
+
- **Canvas sizing discipline.** Match backing size to display size - oversized
|
|
557
557
|
canvases are the #1 silent frame-rate killer.
|
|
558
558
|
- **Reuse sprites and draw calls**; redraw only what changed.
|
|
559
559
|
- **No synchronous work in the loop.** No storage writes, no fetch, no heavy
|
|
@@ -584,14 +584,14 @@ bring axios from "axios"
|
|
|
584
584
|
bring geometry from "./helpers.pln"
|
|
585
585
|
```
|
|
586
586
|
|
|
587
|
-
**Call member chains**
|
|
587
|
+
**Call member chains** - no special syntax:
|
|
588
588
|
|
|
589
589
|
```plainscript
|
|
590
590
|
crypto.createHash("sha256").update("abc").digest("hex")
|
|
591
591
|
mesh.scale.set(2, 2, 2)
|
|
592
592
|
```
|
|
593
593
|
|
|
594
|
-
**Construct with `new Type(args)`**
|
|
594
|
+
**Construct with `new Type(args)`** - statement start, `remember`, arguments,
|
|
595
595
|
member chains, or bare without parens:
|
|
596
596
|
|
|
597
597
|
```plainscript
|
|
@@ -613,9 +613,9 @@ window.addEventListener("resize", fitWindow)
|
|
|
613
613
|
button.onclick becomes fitWindow
|
|
614
614
|
```
|
|
615
615
|
|
|
616
|
-
**Promises**
|
|
616
|
+
**Promises** - browser builtins (`loadImage`, `fetchJson`, `loadAudio`)
|
|
617
617
|
auto-await. Raw interop uses `await` / `wait for`; errors use the repository's
|
|
618
|
-
`try/recover` idiom
|
|
618
|
+
`try/recover` idiom - never `.then`:
|
|
619
619
|
|
|
620
620
|
```plainscript
|
|
621
621
|
remember response as await fetch("/api/state")
|
|
@@ -629,9 +629,10 @@ recover as err
|
|
|
629
629
|
show message of err
|
|
630
630
|
finally
|
|
631
631
|
show "done"
|
|
632
|
+
done
|
|
632
633
|
```
|
|
633
634
|
|
|
634
|
-
**Typed arrays / binary**
|
|
635
|
+
**Typed arrays / binary** - `remember buffer as new Uint8Array(64)` and index
|
|
635
636
|
with `buffer[0] becomes 255`.
|
|
636
637
|
|
|
637
638
|
**Arrays, objects, JSON:**
|
|
@@ -645,7 +646,7 @@ remember config as jsonDecode(rawJson)
|
|
|
645
646
|
```
|
|
646
647
|
|
|
647
648
|
Rules: no `=>`, `.then`, `let/const`, braces, or semicolons in `.pln`. A
|
|
648
|
-
library is *called* from PlainScript
|
|
649
|
+
library is *called* from PlainScript - symbol, flow, and state stay in
|
|
649
650
|
PlainScript. Need a stateful callback? Define a `make` function that reads the
|
|
650
651
|
shared state you already have.
|
|
651
652
|
|
|
@@ -686,7 +687,7 @@ Debug by checking `game.js` for that shape (`addEventListener`,
|
|
|
686
687
|
| Variable named for a keyword/builtin | Rename (`start`, `now`, `get`, `set`, `reply`, `from`, `as`, `of`, `in`, `json`, `bytes`, `update`, `status` are taken) |
|
|
687
688
|
| Writing `is most` for `<=` | Use `is at most` (`is most` is not a comparison) |
|
|
688
689
|
| Storing colors as opaque decimals (`4244579`) | Hex literal `0x40c463` is supported (or a `"#40c463"` string) |
|
|
689
|
-
| `make update` / `make get` as function names | Rename
|
|
690
|
+
| `make update` / `make get` as function names | Rename - those are keywords |
|
|
690
691
|
| Bare `keys["ArrowLeft"]` in `if` | Compare: `if keys["ArrowLeft"] is true` |
|
|
691
692
|
| Audio with no user gesture | `ctx.resume()` from a click/keydown handler |
|
|
692
693
|
| Drawing before assets load | Gate scene start on a loaded flag |
|
|
@@ -833,7 +834,7 @@ requestAnimationFrame(loop)
|
|
|
833
834
|
For games up to a few hundred lines, one `.pln` file is correct: one `state`
|
|
834
835
|
record owned by the loop, one rAF loop (`every frame` or the dt form) that
|
|
835
836
|
steps then draws, one input set (a `keys{}` map plus one pointer handler), and
|
|
836
|
-
plain DOM updates for the HUD. File count should track surface area
|
|
837
|
+
plain DOM updates for the HUD. File count should track surface area - a small
|
|
837
838
|
game in five files is as wrong as a big game in one.
|
|
838
839
|
|
|
839
840
|
### 19.2 Large games
|
|
@@ -850,15 +851,15 @@ remember firstWave as spawnEnemy(320, 40)
|
|
|
850
851
|
|
|
851
852
|
A proven structure:
|
|
852
853
|
|
|
853
|
-
- **Entity factories**
|
|
854
|
+
- **Entity factories** - `define a kind` plus a `make spawnThing()` returning a
|
|
854
855
|
new instance; one file per entity family.
|
|
855
|
-
- **Systems as `make` functions**
|
|
856
|
+
- **Systems as `make` functions** - one system (movement, collision, rendering,
|
|
856
857
|
scoring) per function, run in order by the loop.
|
|
857
|
-
- **Scene/state table**
|
|
858
|
+
- **Scene/state table** - a state record or switch with explicit `attract`,
|
|
858
859
|
`play`, and `gameover` states.
|
|
859
|
-
- **Asset manifest**
|
|
860
|
+
- **Asset manifest** - one `assets` record of URLs loaded at boot; scenes look
|
|
860
861
|
up paths instead of hardcoding.
|
|
861
|
-
- **A server when networking**
|
|
862
|
+
- **A server when networking** - own `server.pln` with `websocket server`,
|
|
862
863
|
authority checks, and snapshot broadcasts; the client is a pure renderer +
|
|
863
864
|
input reporter.
|
|
864
865
|
|
|
@@ -887,7 +888,7 @@ APIs stay libraries you call.
|
|
|
887
888
|
|
|
888
889
|
## Appendix A: Canonical snippets quick reference
|
|
889
890
|
|
|
890
|
-
Every line below is verified canonical form
|
|
891
|
+
Every line below is verified canonical form - copy it exactly:
|
|
891
892
|
|
|
892
893
|
```plainscript
|
|
893
894
|
remember canvas as document.getElementById("game")
|
|
@@ -909,7 +910,7 @@ remember bg as loadImage("img.png")
|
|
|
909
910
|
|
|
910
911
|
Runnable, maintained reference implementations live in:
|
|
911
912
|
|
|
912
|
-
- `examples/canvas-game`
|
|
913
|
-
- `examples/browser-interactive`
|
|
914
|
-
- `examples/three-dimensional`
|
|
915
|
-
- `examples/javascript-library`
|
|
913
|
+
- `examples/canvas-game` - canvas 2D dodge game (keys map + `every frame` + delta time + kinds + restart).
|
|
914
|
+
- `examples/browser-interactive` - DOM-first interactive app (`when ... happens`, `classList`, innerHTML/textContent).
|
|
915
|
+
- `examples/three-dimensional` - WebGL 3D scene via the global `THREE` object.
|
|
916
|
+
- `examples/javascript-library` - an npm library (`bring THREE from "three"`), callbacks, and `fetchJson`.
|
package/docs/PLAINSCRIPT-SPEC.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# PlainScript 1.0.
|
|
1
|
+
# PlainScript 1.0.361 language specification
|
|
2
2
|
|
|
3
3
|
This reference covers the syntax implemented by `compiler/lexer.js` and
|
|
4
4
|
`compiler/parser.js`. The runtime it generates lives in
|
|
@@ -230,6 +230,7 @@ recover as error
|
|
|
230
230
|
show message of error
|
|
231
231
|
finally
|
|
232
232
|
show "finished"
|
|
233
|
+
done
|
|
233
234
|
|
|
234
235
|
retry 3 times every 1 second
|
|
235
236
|
show "retry"
|
|
@@ -311,7 +312,7 @@ accepts the following clauses:
|
|
|
311
312
|
| Clause | Purpose |
|
|
312
313
|
|--------|---------|
|
|
313
314
|
| `auth "<folder>"` | Path where session credentials persist across restarts. |
|
|
314
|
-
| `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@
|
|
315
|
+
| `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@whiskeysockets/baileys`). |
|
|
315
316
|
| `login qr` | Authenticate by scanning a QR code in the terminal. |
|
|
316
317
|
| `login pairing "<phone>"` | Authenticate by entering a phone number (digits only, no `+`). The argument may also be an expression such as `env("WHATSAPP_PHONE")`. |
|
|
317
318
|
| `on message ... done` | Handler that fires for every incoming message. |
|
|
@@ -326,7 +327,7 @@ include `message.text`, `message.type`, `message.mtype`, `message.caption`,
|
|
|
326
327
|
```plainscript
|
|
327
328
|
whatsapp bot
|
|
328
329
|
auth "plain-script-whatsapp"
|
|
329
|
-
use baileys "@
|
|
330
|
+
use baileys "@whiskeysockets/baileys"
|
|
330
331
|
login pairing "2348012345678"
|
|
331
332
|
on message
|
|
332
333
|
if message.text is "/start"
|
|
@@ -377,12 +378,12 @@ documents, buttons, lists, and more. The following helpers are available:
|
|
|
377
378
|
`"reaction"`, `"contact"`, `"contacts"`, `"location"`, `"live-location"`,
|
|
378
379
|
`"poll"`, `"group-invite"`, and `"other"`.
|
|
379
380
|
|
|
380
|
-
**Full example
|
|
381
|
+
**Full example - media, buttons, and list replies:**
|
|
381
382
|
|
|
382
383
|
```plainscript
|
|
383
384
|
whatsapp bot
|
|
384
385
|
auth "plain-script-whatsapp"
|
|
385
|
-
use baileys "@
|
|
386
|
+
use baileys "@whiskeysockets/baileys"
|
|
386
387
|
login pairing env("WHATSAPP_PHONE")
|
|
387
388
|
on message
|
|
388
389
|
log message
|
|
@@ -448,7 +449,7 @@ PlainScript compiles to Plain JavaScript that runs in modern browsers. A
|
|
|
448
449
|
`web app` can serve the page itself, or you compile a `.pln` to `game.js` and
|
|
449
450
|
serve it with any static host. The tested workflows are:
|
|
450
451
|
|
|
451
|
-
1. **Static**, served by PlainScript
|
|
452
|
+
1. **Static**, served by PlainScript - `web app` + `serve folder "public"` +
|
|
452
453
|
a `reply file` route that returns `index.html`:
|
|
453
454
|
|
|
454
455
|
```plainscript
|
|
@@ -460,10 +461,10 @@ serve it with any static host. The tested workflows are:
|
|
|
460
461
|
start 8000
|
|
461
462
|
```
|
|
462
463
|
|
|
463
|
-
2. **Static**, any host
|
|
464
|
+
2. **Static**, any host - `node compiler/cli.js build game.pln -o public/game.js`
|
|
464
465
|
and include `<script src="game.js">` after the canvas and any CDN globals.
|
|
465
466
|
|
|
466
|
-
Canvas apps use the same value/property interop as everything else
|
|
467
|
+
Canvas apps use the same value/property interop as everything else - canvas
|
|
467
468
|
state is assigned with `becomes`, then a draw call runs:
|
|
468
469
|
|
|
469
470
|
```plainscript
|
|
@@ -475,7 +476,7 @@ ctx.fillRect(0, 0, 320, 240)
|
|
|
475
476
|
|
|
476
477
|
Animation is `requestAnimationFrame`. Two native loop forms: `every frame`
|
|
477
478
|
(timing-agnostic) and an explicit rAF callback with delta seconds for
|
|
478
|
-
frame-rate-independent movement
|
|
479
|
+
frame-rate-independent movement - see `docs/GAME-PROMPT.md` for the canonical
|
|
479
480
|
`dt` idiom. Input uses the DOM event form; `when <target> "<event>" happens`
|
|
480
481
|
becomes `addEventListener`, and reading a key map uses a boolean comparison:
|
|
481
482
|
|
|
@@ -493,7 +494,7 @@ if keys["ArrowLeft"] is true
|
|
|
493
494
|
done
|
|
494
495
|
```
|
|
495
496
|
|
|
496
|
-
Browser builtins are either direct helpers or auto-awaited promises
|
|
497
|
+
Browser builtins are either direct helpers or auto-awaited promises - no
|
|
497
498
|
`await` is written for the loaders:
|
|
498
499
|
|
|
499
500
|
- `select("canvas")` / `selectAll(".card")` / `parseHTML("<div>...</div>")`
|
|
@@ -502,7 +503,7 @@ Browser builtins are either direct helpers or auto-awaited promises — no
|
|
|
502
503
|
→ `{ok, status, data: Uint8Array}`
|
|
503
504
|
- `readDataUrl(file)` → a `data:` URL string for a `File` (from
|
|
504
505
|
`droppedFiles(event)` or a file input)
|
|
505
|
-
- `audioContext()` + `playTone(frequency, seconds, options)`
|
|
506
|
+
- `audioContext()` + `playTone(frequency, seconds, options)` - start from a
|
|
506
507
|
user-gesture handler (`ctx.resume()`)
|
|
507
508
|
- `localPoint(event, canvas)` maps client to canvas coordinates
|
|
508
509
|
- `gamepads()` returns connected pads; `droppedFiles(event)` reads drag-drop
|
|
@@ -513,7 +514,7 @@ Browser builtins are either direct helpers or auto-awaited promises — no
|
|
|
513
514
|
`setItem` plus `jsonEncode` / `jsonDecode` (JSON is a builtin data type)
|
|
514
515
|
|
|
515
516
|
WebGL runs through the WebGL2 canvas API (`webglContext(canvas)`, `glShader`,
|
|
516
|
-
`glProgram`, `glBuffer`
|
|
517
|
+
`glProgram`, `glBuffer` - all protected by teaching errors) or a library such
|
|
517
518
|
as Three.js constructed interop-style with `new`. WebGPU is available via its
|
|
518
519
|
canvas API.
|
|
519
520
|
A detailed, expanding guide for browser games lives in
|
|
@@ -531,7 +532,7 @@ remember engine as matter.Engine.create()
|
|
|
531
532
|
remember scene as new THREE.Scene()
|
|
532
533
|
```
|
|
533
534
|
|
|
534
|
-
Call anything
|
|
535
|
+
Call anything - member chains need no special syntax, and there is no wrapper
|
|
535
536
|
around values:
|
|
536
537
|
|
|
537
538
|
```plainscript
|
|
@@ -539,9 +540,9 @@ crypto.createHash("sha256").update("abc").digest("hex")
|
|
|
539
540
|
mesh.scale.set(2, 2, 2)
|
|
540
541
|
```
|
|
541
542
|
|
|
542
|
-
Construct with `new Type(args)`
|
|
543
|
+
Construct with `new Type(args)` - as a statement, in `remember`, as an
|
|
543
544
|
argument, or bare without parens (`new Enemy`). A `make` function reference is
|
|
544
|
-
a first-class value
|
|
545
|
+
a first-class value - pass it as a callback:
|
|
545
546
|
|
|
546
547
|
```plainscript
|
|
547
548
|
make fitWindow()
|
package/docs/index.html
CHANGED
|
@@ -3,9 +3,9 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
-
<meta name="description" content="PlainScript 1.0.
|
|
6
|
+
<meta name="description" content="PlainScript 1.0.361 language reference and examples">
|
|
7
7
|
<meta name="theme-color" content="#070c16">
|
|
8
|
-
<title>PlainScript 1.0.
|
|
8
|
+
<title>PlainScript 1.0.361</title>
|
|
9
9
|
|
|
10
10
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
11
11
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
<a class="nav-logo" href="#">
|
|
22
22
|
<img class="nav-logo-image" src="logo-pln.jpg" alt="">
|
|
23
23
|
<span>PlainScript</span>
|
|
24
|
-
<span class="logo-ver">1.0.
|
|
24
|
+
<span class="logo-ver">1.0.361</span>
|
|
25
25
|
</a>
|
|
26
26
|
<button class="nav-toggle" id="nav-toggle" aria-label="Toggle navigation" aria-expanded="false" aria-controls="nav-links">
|
|
27
27
|
<span class="nav-toggle-bar"></span>
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
<div class="hero-headline-block">
|
|
45
45
|
<p class="hero-badge" data-reveal>an intent-oriented language for node.js</p>
|
|
46
46
|
<h1 class="hero-title"><span class="kw">remember</span> the sentence <span class="kw">as</span> the program.<br><span class="kw">show</span> the result <span class="kw">when</span> the meaning is clear.</h1>
|
|
47
|
-
<p class="hero-lead">Write what you want in plain words. PlainScript checks it, then turns it into readable JavaScript
|
|
47
|
+
<p class="hero-lead">Write what you want in plain words. PlainScript checks it, then turns it into readable JavaScript - no boilerplate, no hidden steps.</p>
|
|
48
48
|
<div class="hero-actions">
|
|
49
49
|
<span class="hero-install-label">install</span>
|
|
50
50
|
<a class="button" href="#quickstart">npx plainscript new hello</a>
|
|
@@ -82,14 +82,21 @@ npm start</code></pre>
|
|
|
82
82
|
<div class="container">
|
|
83
83
|
<p class="section-tag" data-reveal>Language</p>
|
|
84
84
|
<h2 class="section-title" data-reveal>A small set of words you already know.</h2>
|
|
85
|
+
<p class="section-lead" data-reveal>Every construct is a sentence: a verb opens a block, <code>done</code> closes it, and values, functions, and collections nest freely - a comparison, a lambda, and a list all fit anywhere a value fits.</p>
|
|
85
86
|
<div class="feature-grid">
|
|
86
87
|
<article class="feature-card" data-reveal><h3>Variables</h3><p>Store values with <code>remember name as "Ada"</code> and change them with <code>becomes</code>.</p></article>
|
|
87
88
|
<article class="feature-card" data-reveal><h3>Conditions</h3><p>Compare things with <code>is at least</code>, <code>contains</code>, <code>between</code>, and more.</p></article>
|
|
89
|
+
<article class="feature-card" data-reveal><h3>Choice</h3><p>Pick a value inline with <code>choosing ok is true then "online" otherwise "offline"</code>, or an <code>if / otherwise</code> block for steps.</p></article>
|
|
88
90
|
<article class="feature-card" data-reveal><h3>Functions</h3><p>Create functions with <code>make</code>, return with <code>give</code>, and close with <code>done</code>.</p></article>
|
|
91
|
+
<article class="feature-card" data-reveal><h3>Lambdas</h3><p>Write snippets as values: <code>(n) -> n * 2</code>, or a block with <code>(n) do ... done</code>.</p></article>
|
|
92
|
+
<article class="feature-card" data-reveal><h3>Loops</h3><p>Iterate with <code>for each item in list</code>, <code>for index i from 0 to 9</code>, or <code>repeat N times</code>.</p></article>
|
|
89
93
|
<article class="feature-card" data-reveal><h3>Records</h3><p>Model your data with record kinds and easy constructors.</p></article>
|
|
90
94
|
<article class="feature-card" data-reveal><h3>Modules</h3><p>Import code with <code>bring ... from</code>, <code>@/</code> aliases, and re-exports.</p></article>
|
|
91
95
|
<article class="feature-card" data-reveal><h3>Compound Types</h3><p>Use dictionaries, sets, and tuples with unpacking.</p></article>
|
|
96
|
+
<article class="feature-card" data-reveal><h3>Errors</h3><p>Guard against failure with <code>try / recover as err / finally</code> and <code>raise</code>.</p></article>
|
|
97
|
+
<article class="feature-card" data-reveal><h3>Async and events</h3><p>Await promises with <code>wait for</code>, and bind events with <code>when element "click" happens</code>.</p></article>
|
|
92
98
|
<article class="feature-card" data-reveal><h3>Web apps</h3><p>Set up routes, JSON responses, sessions, cookies, uploads, and auth.</p></article>
|
|
99
|
+
<article class="feature-card" data-reveal><h3>HTTP client</h3><p>Call APIs with <code>get url</code> / <code>post url with body</code> and read <code>status of response</code>.</p></article>
|
|
93
100
|
<article class="feature-card" data-reveal><h3>Data and async</h3><p>Work with SQLite, HTTP, files, schedules, concurrency, and WebSockets.</p></article>
|
|
94
101
|
<article class="feature-card" data-reveal><h3>AI providers</h3><p>Call Groq and other OpenAI-compatible providers using your own keys.</p></article>
|
|
95
102
|
</div>
|
|
@@ -110,7 +117,7 @@ npm start</code></pre>
|
|
|
110
117
|
<div class="container">
|
|
111
118
|
<p class="section-tag" data-reveal>Feature library</p>
|
|
112
119
|
<h2 class="section-title" data-reveal>Examples you can try today.</h2>
|
|
113
|
-
<p class="section-lead">These snippets use the PlainScript 1.0.
|
|
120
|
+
<p class="section-lead">These snippets use the PlainScript 1.0.361 grammar.</p>
|
|
114
121
|
<div class="library-toolbar" data-reveal>
|
|
115
122
|
<label class="sr-only" for="lib-search">Search examples</label>
|
|
116
123
|
<input id="lib-search" class="lib-search-input" type="search" placeholder="Search examples">
|
|
@@ -139,7 +146,7 @@ npm start</code></pre>
|
|
|
139
146
|
</main>
|
|
140
147
|
|
|
141
148
|
<footer class="site-footer">
|
|
142
|
-
<div class="container footer-bottom"><span>PlainScript</span><span>1.0.
|
|
149
|
+
<div class="container footer-bottom"><span>PlainScript</span><span>1.0.361</span></div>
|
|
143
150
|
</footer>
|
|
144
151
|
|
|
145
152
|
<script src="https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js"></script>
|
package/docs/website/script.js
CHANGED
|
@@ -288,7 +288,7 @@
|
|
|
288
288
|
{ category: "web", name: "Web routes", description: "Build an HTTP app with JSON routes.", source: 'web app\nroute get "/health"\n reply json\n ok is true\n done\ndone\nstart 3000' },
|
|
289
289
|
{ category: "web", name: "HTTP client", description: "Fetch data from a URL.", source: 'remember response as get "https://example.com/data" timeout 5000\nshow response.status' },
|
|
290
290
|
{ category: "web", name: "Auth and sessions", description: "Protect routes and track visitors.", source: 'web app\nenable sessions "session-secret"\nrequire api key from env("API_KEY")\nroute get "/me"\n reply json\n user is user of session of request\n done\ndone' },
|
|
291
|
-
{ category: "runtime", name: "Async errors", description: "Handle errors gracefully.", source: 'try\n remember result as get "https://example.com" timeout 5000\nrecover as error\n show message of error\nfinally\n show "finished"' },
|
|
291
|
+
{ category: "runtime", name: "Async errors", description: "Handle errors gracefully.", source: 'try\n remember result as get "https://example.com" timeout 5000\nrecover as error\n show message of error\nfinally\n show "finished"\ndone' },
|
|
292
292
|
{ category: "runtime", name: "Concurrency", description: "Run several tasks at once.", source: 'remember results as allOf(list with firstJob(), secondJob())\nremember quick as withTimeout(firstJob(), 1000)\nshow results' },
|
|
293
293
|
{ category: "runtime", name: "WebSockets", description: "Chat and push updates live.", source: 'websocket server on 8080\n when socket connects\n send socket "connected"\n done\n when socket sends message\n broadcast message\n done\ndone' },
|
|
294
294
|
{ category: "runtime", name: "Cache", description: "Keep values ready with a TTL.", source: 'cache env("REDIS_URL")\ncacheSet("status", "ready", 60)\nremember status as cacheGet("status")' },
|
package/docs/website/style.css
CHANGED
|
@@ -26,7 +26,7 @@ code { font-size: .92em; color: #b9e6c7; }
|
|
|
26
26
|
|
|
27
27
|
.container { width: min(1120px, calc(100% - 40px)); margin: 0 auto; }
|
|
28
28
|
|
|
29
|
-
/* Full-bleed animated background
|
|
29
|
+
/* Full-bleed animated background - flat, no glow */
|
|
30
30
|
.bg-scrim, #bg-canvas {
|
|
31
31
|
position: fixed;
|
|
32
32
|
inset: 0;
|
|
@@ -84,7 +84,7 @@ code { font-size: .92em; color: #b9e6c7; }
|
|
|
84
84
|
.nav-toggle[aria-expanded="true"] .nav-toggle-bar:nth-child(2) { opacity: 0; }
|
|
85
85
|
.nav-toggle[aria-expanded="true"] .nav-toggle-bar:nth-child(3) { transform: translateY(-7px) rotate(-45deg); }
|
|
86
86
|
|
|
87
|
-
/* Hero
|
|
87
|
+
/* Hero - asymmetric, the headline is the demo */
|
|
88
88
|
.hero { position: relative; border-bottom: 1px solid var(--line); }
|
|
89
89
|
.hero-content { position: relative; z-index: 1; padding: 0; }
|
|
90
90
|
.hero-grid {
|
|
@@ -226,7 +226,7 @@ pre code {
|
|
|
226
226
|
.section-lead { color: var(--muted); }
|
|
227
227
|
.three-column, .feature-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 1px; background: var(--line); border: 1px solid var(--line); }
|
|
228
228
|
|
|
229
|
-
/* Cards
|
|
229
|
+
/* Cards - flat, hairline-separated, no shadow */
|
|
230
230
|
.info-card, .feature-card, .library-card {
|
|
231
231
|
padding: 24px;
|
|
232
232
|
border: none;
|
package/examples/arrays.pln
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
// PlainScript 1.0.
|
|
1
|
+
// PlainScript 1.0.361: asynchronous work and error recovery.
|
|
2
2
|
|
|
3
3
|
make loadProfile(id)
|
|
4
4
|
wait for sleep(10)
|
|
@@ -12,6 +12,7 @@ recover as err
|
|
|
12
12
|
show message of err
|
|
13
13
|
finally
|
|
14
14
|
show "request complete"
|
|
15
|
+
done
|
|
15
16
|
|
|
16
17
|
retry 3 times every 2 seconds
|
|
17
18
|
show "retrying"
|
package/examples/auth-api.pln
CHANGED