97 lines
15 KiB
Markdown
97 lines
15 KiB
Markdown
# Logigate
|
||
|
||
Logic circuit editor and simulator at <https://logicate.blax.at>, in the spirit of the game "Turing Complete". NAND is the only gate. You draw circuits with it, package them as components, and reuse those in bigger circuits, up to a CPU. Everything runs live while you draw: green wires carry a 1, grey wires a 0.
|
||
|
||
Nuxt 4 (client-only editor, `ssr: false`), Tailwind CSS v4, Lucide icons via `@nuxt/icon`, Inter and JetBrains Mono self-hosted via `@nuxt/fonts`. No tracking. Projects live in the browser's localStorage, and in the user's account when signed in. The server part is the share-link and account API.
|
||
|
||
## What it does
|
||
|
||
- Parts: NAND, input switch, output pin, lamp, push button, clock, constant 1, ground, hex display, pixel, cable bundle and split, input panel, note.
|
||
- Lamps and output pins pass their signal on: the pin on their right carries the same value, so a lamp can sit in the middle of a wire.
|
||
- Gates with more inputs: a placed AND, OR, XOR, NAND or NOR (built in, from the examples, or your own) has an "Inputs" setting from 2 to 16. The wide version is a component built as a balanced tree of the two-input gate (NAND and NOR as the plain gate plus a final inverted one), made once per gate and width in "Wide gates" and reused; transistors count honestly and changes to the two-input gate carry through. Which gates qualify is read off their truth table ([app/lib/logic/wide.ts](app/lib/logic/wide.ts)).
|
||
- Campaign (Projects → New campaign): you start with NAND, inputs, outputs, lamps and notes, and no examples. Each challenge opens once the ones it builds on are solved (NOT → AND, OR, SR Latch → …), and your own solution becomes a part you can place. Other basic parts unlock on the way: constants with NOT, the input panel with AND, hex display and pixel with the decoder, cables with Adder 2, the button with the SR latch, the clock with the D latch. Rules in [app/lib/logic/progress.ts](app/lib/logic/progress.ts). Sandbox projects keep everything open.
|
||
- Puzzles: "Publish as puzzle" (This circuit) turns a circuit into a link `/puzzle/<id>`. Only its behaviour is published, as a truth table, or for circuits with memory as a run of input changes from power-on; the circuit stays private. Whoever opens the link gets the puzzle in their project, sees the target and the author's transistor count, and after a pass their solution goes to the server, which re-runs the checks and counts the transistors itself (with a fixed work budget) and keeps each player's best. The board shows everyone's transistor counts and your place. The puzzle of the week is generated from the ISO week, the same for everyone: three or four inputs, one or two outputs, each depending on every input. Players are anonymous ids per browser.
|
||
- Sound (speaker in the top bar; volume and clock ticks under Display): clicks for placing, wiring, switches and buttons, a tick per clock cycle up to 8 Hz (off by default), and jingles for a solve, a failed check, unlocks and new records. All synthesised with Web Audio, no sound files ([app/lib/audio.ts](app/lib/audio.ts)).
|
||
- Transistors: every component shows how many it takes, counted as a CMOS NAND (4 transistors) per gate at every depth: in the palette, its settings and the circuit stats. Each challenge keeps your record, the fewest transistors of any passing solution, and says so when you beat it.
|
||
- Cables: a bundle gathers 2 to 32 wires into one thick cable, a split fans it out again in the same order; one bundle can feed several splits. Select some wires and press "Bundle into cable" to have both ends placed for you (the cable takes the wires' colour); "Remove cable" turns it back into single wires. A cable end only joins another cable end, and the cable shows its width.
|
||
- Pixels and screens: a pixel is a one-grid square that lights at 1, in five colours. Inside a component all pixels show on its box as one screen without gaps (every column and row they sit on becomes one of the screen), so you build your own LCD; see "Screen 4×4" and "Demo: Screen".
|
||
- Input panel: one part with a column of controls; each row is a switch, button or clock. "Attach input panel" on a placed component docks one to its left with a row per free input, lined up with the pins and named after them. A docked panel moves with its component, gets a row when the component gains an input and loses it when the pin goes; inputs that are wired elsewhere, and rows you remove, are left alone. Inside a component a switch row keeps its position and a button row is 0.
|
||
- Automatic names: copies continue a series (D0 copied gives D1, D2; A gives B), and so does placing a new input or output after a numbered one. A switch, button, lamp or output pin without a name of its own (or with an automatic one) takes the name of the component pin it gets wired to, made unique (Cin, Cin2); a name typed by hand is kept. On the canvas, a switch, button, clock, lamp or output pin without a name typed by hand shows the name of the component pin it is wired to, dimmed and in italics (or its automatic name, also dimmed); the name follows the wiring as it changes.
|
||
- Every circuit is a component. Its input and output nodes become its pins, ordered top to bottom. Double-click a component to open it.
|
||
- Lamps and hex displays inside a component show on its box, with their labels, lit by that instance's state. They are laid out in rows the way they sit inside. A checkbox in the inspector turns this off per component.
|
||
- Clicking anything opens its settings on the right. Parts can be swapped in place (wires stay on the pins in the same position): NAND and components with each other, switch/button/clock/constants with each other, output/lamp/display with each other. Clocks have their own frequency or follow the top bar. Switches and buttons can get a keyboard key. Lamps and displays have colours, notes have sizes, components a name on the canvas. Components can be unpacked into their parts or given their own copy of the definition; any part can have all its wires unlinked.
|
||
- Select parts and press "Make component" to turn them into a new component; wires crossing the selection become pins.
|
||
- Gate symbols in IEC 60617 (DIN, default) or ANSI. A component with one output can be drawn as a gate symbol.
|
||
- Wires of different signals never share a line: auto-routed wires pick a free column or a detour, and anything still clashing (hand-placed bends) is drawn on its own lane. Crossings are drawn as a bow, triangle, bridge, gap or plain crossing (Display settings on the right with nothing selected). Clicking a junction dot selects its whole signal.
|
||
- Connecting: drag from a pin, or click a pin and then the other one. While a wire is drawn, every pin it can go to is ringed (dashed when it already has a wire, which would be replaced); dropping it on a part uses that part's next free pin. "Connect one by one" (W, or the button with several parts selected; on a component "Wire one by one: Inputs / Outputs") numbers the pins of the selection top to bottom and wires them in turn, one click each; clicking the same component again and again fills its pins in order.
|
||
- Tidy wiring (Display settings, or "Tidy all wires", which also drops hand-placed bends): every forward wire takes its vertical step in the free gap right in front of the part it feeds. All wires entering parts at the same column are ordered together (each goes where it adds the fewest crossings) and laid out as one compact staircase a grid step apart, slid sideways to where it runs along no other signal; one signal shares one trunk. Only the columns of that gap are looked at, so it stays cheap. On the 4-bit adder without hand routing this cuts crossings from 32 to 18.
|
||
- Wire editing: drag any segment (a stub keeps the pin end straight), drag corner squares, Alt+drag to pull out a new bend, Ctrl+drag to branch a new wire off a signal, double-click to select the whole signal, Shift+click and box selection for several wires, arrow keys to shift them, six colour tags.
|
||
- Several projects per browser (Projects dialog: open, rename, duplicate, delete). Export a project file, open a file as a new project, or add the components of a file to the open project.
|
||
- Accounts: email and password. Signed in, every project in the browser is also kept in the account and synced in both directions (on sign-in, on focus, every minute, and two seconds after a change). If two computers changed the same project, both versions are kept. The untouched starter project of a new browser is not uploaded; signing in there opens your latest project instead.
|
||
- Share links: `/p/<id>`. The creator's changes save to the link automatically. Anyone else who opens it gets their own copy; their first edit detaches it from the link.
|
||
- Truth table, NAND count, gate delay, and loop detection for the open circuit. The table can go full screen, be downloaded as CSV or copied as a Markdown table; the row the switches are set to is highlighted.
|
||
- 17 challenges (NOT up to a D flip-flop) checked against a truth table or a step sequence.
|
||
- Example library, all built from NAND: NOT, AND, OR, NOR, XOR, XNOR, Mux, Half/Full Adder, SR Latch, D Latch, D Flip-Flop, Register 4, Increment 4, Adder 4, Counter 4, a counter demo with a hex display, and a 4×4 pixel screen with a demo.
|
||
|
||
## How the simulation works
|
||
|
||
All in [app/lib/logic/](app/lib/logic/), plain TypeScript with no Vue dependency:
|
||
|
||
- `compile.ts` flattens the component tree into a list of NAND gates over numbered nets. Chip boundaries and pins are aliases, merged with union-find. Net 0 is constant 0, net 1 constant 1.
|
||
- `sim.ts` is event-driven: a net change queues the gates that read it, and gates run in FIFO order on the newest values. NAND latches settle deterministically; a loop with an odd number of inversions never settles and the top bar shows "Oscillating".
|
||
- Gate outputs are keyed by their path ("chipNode/chipNode/nand"), so latch state survives editing.
|
||
- `analyze.ts` builds truth tables, counts NANDs, computes the longest gate path, and runs challenge tests.
|
||
- `examples.ts` builds the example library with a small builder; `ops.ts` holds project edits (package selection, copy/paste, prune dangling wires, recursion check).
|
||
- `routing.ts` lays out all wires of a circuit (free lanes, detours, separation, crossings, and the tidy layout).
|
||
- `progress.ts` holds the campaign rules; `puzzles.ts` makes, checks and scores puzzles and generates the weekly one (shared with the server, [server/api/puzzles/](server/api/puzzles/), storage in `data/puzzles`).
|
||
- `cables.ts` bundles wires into cables and takes them apart again.
|
||
- `panels.ts` docks input panels to components and keeps them in step; `labels.ts` does series names and names taken from pins.
|
||
- `wires.ts` edits wire routes (segment and corner drags, splits, branches); `project.ts` validates project data for both the browser and the server; `storage.ts` is the browser's project library.
|
||
|
||
The editor UI is in [app/components/editor/](app/components/editor/) with state in [app/composables/useEditor.ts](app/composables/useEditor.ts).
|
||
|
||
## Share links
|
||
|
||
[server/api/p/](server/api/p/): `POST /api/p` stores a project and returns `{ id, key }`; `GET /api/p/:id` reads it; `PUT /api/p/:id` with header `x-edit-key` replaces it. Only a SHA-256 of the key is stored. Each link is one JSON file in `data/shares/` (Nitro fs storage). Limits: 2 MB and 100,000 nodes per project, 30 new links and 600 saves per IP per 10 minutes (in memory). The edit key lives only in the creator's browser (project index in localStorage), never in exported files.
|
||
|
||
## Accounts
|
||
|
||
[server/api/auth/](server/api/auth/) (register, login, logout, me, password, delete) and [server/api/me/projects/](server/api/me/projects/) (list, get, put, delete). Passwords are hashed with scrypt; the session is a random token in an httpOnly, SameSite=Lax cookie, stored server-side as a SHA-256. API calls that change something are refused when their Origin is another site. Storage: `data/users`, `data/sessions`, `data/accounts/<uid>/` with an index (revision per project, deletions for a year), one file per project, and savegames in `h/<project>/`. Each save sends the revision it started from; a mismatch answers 409 and the browser keeps the other version as a copy. Limits: 1000 projects and 100 MB per account, 2 MB per project, login 20 tries per 10 minutes per IP, 10 new accounts per hour per IP.
|
||
|
||
## Power cuts, savegames, backups
|
||
|
||
No database: everything is JSON files under `data/`, which keeps memory use flat. Three layers protect it:
|
||
|
||
- **Crash-safe writes** ([server/utils/safe-fs.ts](server/utils/safe-fs.ts), mounted in [server/plugins/storage.ts](server/plugins/storage.ts)). A save writes a temporary file, flushes it to disk, keeps the current intact version as `<file>.bak` and then renames the new file into place. A power cut at any moment leaves the old or the new version; reading falls back to `.bak` when a file is missing or damaged, and leftover temporary files are removed at start.
|
||
- **Savegames** ([server/utils/history.ts](server/utils/history.ts)). Before a save replaces an account project, its state is kept as a version (at most one per 15 minutes; always before a restore and on deletion). Kept: the newest 30 plus the last of each day for 90 days. Deleted projects stay restorable for 30 days. In the app: Projects dialog, clock icon (restore, or open as copy), and "Recently deleted".
|
||
- **Daily backup** ([server/utils/backup.ts](server/utils/backup.ts), [server/plugins/backup.ts](server/plugins/backup.ts)). Once a day the production server writes all of `data/` into `backups/logigate-YYYY-MM-DD.ndjson.gz`, leaving out damaged files. Kept: the newest 14 plus the first of each month for a year. `backups/` sits next to `data/` on the same disk, so it protects against damaged files and mistakes, not against losing the disk; copy it elsewhere for that.
|
||
|
||
Restore a backup on edgerealm (the current `data/` is moved aside first, so this can be undone):
|
||
|
||
```bash
|
||
cd /mnt/HC_Volume_102040804/srv/logigate
|
||
docker compose stop frontend
|
||
docker run --rm -v "$PWD":/app -w /app node:current-slim node scripts/restore-backup.mjs backups/logigate-2026-10-20.ndjson.gz
|
||
docker compose start frontend
|
||
```
|
||
|
||
In the browser, each localStorage write is atomic, so a power cut there loses at most the last few seconds.
|
||
|
||
## Compatibility
|
||
|
||
Projects saved by earlier releases must keep working. [tests/compat.test.ts](tests/compat.test.ts) loads a project and both browser-storage layouts written by release a241adc ([tests/fixtures/](tests/fixtures/), never edit them) and checks every component's truth table, NAND count and delay. New fields are optional and have defaults.
|
||
|
||
## Develop
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm dev # http://localhost:3000
|
||
pnpm test # engine tests (vitest)
|
||
pnpm typecheck
|
||
pnpm build # .output/
|
||
```
|
||
|
||
## Deploy
|
||
|
||
Same pattern as autismus-spektrum. On edgerealm the repo lives in `/mnt/HC_Volume_102040804/srv/logigate`; run `./deploy.sh` there. It pulls, builds in a one-shot container and recreates the `logigate` container. Share links and accounts live in `data/` and the daily backups in `backups/`, both next to the repo and mounted into the container, so redeploys keep them. Host nginx terminates TLS with the `*.blax.at` wildcard cert and forwards to Traefik, which routes `logicate.blax.at` and `logigate.blax.at` by the labels in [docker-compose.yml](docker-compose.yml).
|