@scenoco-three/editor 0.6.0 → 0.7.0

package/README.md

@@ -1,50 +1,37 @@
 # @scenoco-three/editor
 
-The **standalone editor** for [SceNoCo](https://github.com/RomaRogov/scenoco-three) scenes: a
-static site with a tree, an inspector, transform gizmos and comment-preserving saves. It needs
-nothing from a project and nothing from a server: it opens a scene from a folder on your machine
-or from a URL, builds it live in the page, and writes your changes back into the XML.
-
-It is what the repository publishes to GitHub Pages, and what `npx scenoco-editor` serves locally.
-
-## Opening a scene
-
-**A folder.** A scene is never one file — its geometry, materials and prefabs are files beside it
-— so the editor opens a folder (Chrome and Edge, through the File System Access API), lists every
-scene and prefab in it, and saves back to disk.
-
-**A URL.** Any `.scene.xml` or `.prefab.xml` on the web; what it refers to is fetched relative to
-it. Read-only, since the web is.
-
-The examples the site carries are offered underneath either way.
-
-## What it builds, and what it cannot
-
-The page parses the document with the compiler's own parser (`@scenoco-three/compiler/browser`)
-and builds the scene from the same vocabulary the compiler uses: three's classes and the tag
-packages the site carries (collision, ui, postfx, audio, particles, box2d). Nodes, assets,
-references, placement, prefabs and overrides are all live, stamped with the parser's positions,
-so the tree, the inspector and the gizmos find every element.
-
-It does not run anything, and has no Play. A component or a system is a project's own
-TypeScript, and there is no TypeScript in a static page — so this is an editor of documents:
-move things, arrange the hierarchy, set attributes, save. What it could not build it says rather
-than drops. To see a scene *run*, an agent uses the observer, and a person runs the game.
-
-## CLI
+A visual editor for SceNoCo scenes that is never part of the project. Part of
+[SceNoCo](https://github.com/RomaRogov/scenoco-three).
 
 ```bash
-npx scenoco-editor            # serve the site locally and open it
-npx scenoco-editor --port 5177 --no-open
+npm run dev                  # the game's own dev server, as always
+npx scenoco-editor           # the editor's interface, on http://localhost:5185
 ```
 
-## Building the site
-
-```bash
-npm run build:app             # static/public (the vocabulary, the examples) + dist-app/
-npm run preview:app
-```
-
-## License
-
-MIT
+Then open the game with `?edit` — `http://localhost:5173/?edit` — or any scene or prefab function
+with `?edit&scene=/src/scenes/levels.tsx%23Level2`.
+
+- **The game builds the scene.** In development, `play()` sees `?edit`, builds the scene with the
+  game's own code on the game's own server, and holds it still: no behaviour wakes. Then it loads
+  this package's interface from its URL (`?edit=<url>` to load it from elsewhere).
+- **What you see is live.** A tree of the scene, an inspector — transform, the element's own
+  attributes, the geometry's and material's, every behaviour's fields — and a move / rotate / scale
+  gizmo, with Global or Local handles. A change is applied to the live object the way the scene sets it.
+- **Made for a finger as much as a mouse.** On a phone held upright the node list and the inspector
+  are bottom sheets, one at a time; turned sideways, or on a screen, they are side columns that can
+  both be open. Drag the letter beside a number to scrub it: the scene follows the drag, and the
+  file is written once, when it ends.
+- **What you change is written back, and nothing else is.** The project's `scenoco()` Vite plugin
+  writes one attribute into the `.tsx` file the element came from, splicing its text; comments,
+  layout and every other attribute stay byte for byte. A value it cannot see through — a
+  `material={paint.wall}`, a ref — is shown, not edited. Rotations show in degrees and are written
+  in radians; numbers are rounded to four decimals.
+
+- **Undo puts the text back.** ⌘Z / Ctrl+Z and ⇧⌘Z / Ctrl+Y restore an attribute exactly as it
+  was written — `-Math.PI / 2` too — and survive the reload that removing an attribute needs.
+- **A file changed behind its back is refused.** Every write names the element it means as the
+  editor last read it; if the file was edited elsewhere since, nothing is written and the editor
+  says to reload.
+
+What it does not do yet: add or remove elements, or show what behaviours spawn at runtime
+(nothing runs while editing — `BrickField`'s bricks are not there).

package/bin/serve.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * `scenoco-editor [--port 5185]` — serves the editor's interface for a game's page to load.
+ *
+ * Start the game's own dev server as usual, run this beside it, and open the game with `?edit`:
+ * the page builds the scene, holds it still, and imports the interface from here. Nothing about
+ * the editor is installed in the project.
+ */
+import { createReadStream, existsSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help')) {
+  console.log('scenoco-editor [--port <n>]\n\nServes the editor for a game page opened with ?edit (port 5185 by default).');
+  process.exit(0);
+}
+const port = Number(argv[argv.indexOf('--port') + 1] || 0) || 5185;
+const file = fileURLToPath(new URL('../dist/editor.js', import.meta.url));
+if (!existsSync(file)) {
+  console.error('scenoco-editor: this package has no dist/editor.js — run `npm run build` in packages/editor');
+  process.exit(1);
+}
+
+createServer((req, res) => {
+  // The game's page is on another port, so the module needs CORS to load at all.
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  if (new URL(req.url ?? '/', 'http://x').pathname !== '/editor.js') {
+    res.statusCode = 404;
+    return res.end('Open your game with ?edit — it loads /editor.js from here.');
+  }
+  res.setHeader('Content-Type', 'text/javascript');
+  res.setHeader('Cache-Control', 'no-store');
+  createReadStream(file).pipe(res);
+}).listen(port, () => {
+  console.log(`scenoco-editor: serving on http://localhost:${port}/editor.js — open your game with ?edit`);
+});