CircuitSim - Logic Circuit Editor & Simulator

What is CircuitSim?

CircuitSim is a desktop editor and simulator for digital logic circuits, built with Java 17, libGDX and LWJGL3. You build circuits from gates (AND, OR, XOR, NOT), wire them with multi-bit buses (3, 4 and 8 bits), and watch signals propagate in real time. It’s a full product, not a lab exercise: a free sandbox, a user component system, an in-game electronic guide, and a complete authored campaign.

A Steam release is being prepared - no public build available yet.

The Simulation Core

The heart of the project is a deterministic tri-state simulation engine:

• Three signal states: LOW, HIGH and UNKNOWN. Undefined inputs (like a latch before its first set) propagate as UNKNOWN instead of being silently coerced to a value.
• Combinational feedback: feedback loops are a first-class feature, not a crash. Signals depending on a combinational cycle are treated as inactive, and sustained oscillation is detected rather than freezing the evaluator.
• Sequential logic: latches and registers hold state across evaluations, which is what makes building memory - and eventually a CPU - possible.
• Multi-bit buses: splitters and mergers for 3, 4 and 8-bit buses let you model real word-width datapaths.
• Recursive composition: the boundaries of custom components are evaluated inside the same simulation graph, so a component containing a component containing a latch all resolves in one deterministic pass.

The evaluation is memoized per logic revision into an immutable SignalSnapshot - the graph is walked once, then every consumer (rendering, HUD, save capture) reads from identity-keyed tables with no re-traversal.

Custom Components & the Sandbox

The sandbox is total: any arrangement of gates can be encapsulated into a custom component with its own boundary pins, saved to disk, archived and reused anywhere in the campaign. Compilation produces a definition with a stable serialized identity registered in a behavior registry - so:

• Adding a component type never touches a central switch.
• Saving a campaign never breaks when the simulator evolves.
• Your adder, your latch, your ALU are first-class parts of the builder palette.

This turns the sandbox into a genuine design tool: build it, name it, drop it in another circuit, archive it for later.

The Campaign: From an Inverter to a 4-bit CPU

The campaign is the spine of the game - 89 challenges, 179 narrative scenes, fully written in French and English, all data-driven JSON (ports, allowed components, constraints, success vectors per challenge). The progression arc:

1. Signal fundamentals - inverters, gates, bus splitting, first memories
2. Combinational design - half/full adders, 2-bit and 4-bit adders, decoders, selectors
3. Sequential logic - latches, edge-triggered memory, command registers, flag registers
4. The CPU arc - instruction format, opcode decoding, fetch cycle, fetch address/advance, datapath, control unit, sequencer - culminating in assembling the complete 4-bit CPU core: datapath + instruction register + control unit + sequencer, driven by external ROM data, with live PC, MAR, IR and register outputs.

You literally build the CPU from gates you’ve been assembling all game. Every challenge runs in an isolated workspace with exactly the components it allows, so you can’t cheat past the lesson.

Architecture

Two Gradle modules, strict layering:

circuit/
├── core/    # domain, simulation, editor, saves, campaign, i18n
│   ├── component/      Circuit, components, pins, connections, revisions
│   ├── simulation/     SignalSnapshot, behaviors, feedback resolution
│   ├── editor/         interactions, EditorCommand, renderers, pipeline
│   ├── save/           serialization, autosave worker, custom components
│   ├── campaign/       JSON loading, progression, narrative, objectives
│   └── i18n/           UI, guide and campaign catalogs (FR/EN)
└── lwjgl3/  # desktop launcher, natives, packaging

Key invariants that keep 57k lines maintainable:

• One mutation path: all structural changes flow through the Circuit API, which validates placement collisions, pin direction, wired-input uniqueness and component ownership.
• Reversible editor commands: placement, wiring, deletion and (group) moves are EditorCommands with a bounded 256-deep history - undo/redo can never bypass the domain API.
• Three revisions, three consumers: logicRevision → simulation memo, topologyRevision → scene caches, spatialRevision → the spatial index. Each subsystem only rebuilds when its revision changes.
• Rendering is a projection: the render pipeline reads snapshots and reusable render frames. The world state is never inspected from a shader or draw call.

Performance engineering

• Spatial index in 16-cell chunks, rebuilt only on spatial/topology revisions, indexing each segment of an orthogonal cable (not its bounding box); the same index powers pixel-stable pin/cable hit-testing.
• Zero-allocation hot path: reusable mesh caches for gate geometry, per-identity render contexts updated in place during drags, LOD that drops pins below 9 px/cell and text below 18 px.
• GLES2 post-processing: Dual-Kawase bloom with emissive extraction in linear light, analytic SDF grid, HUD composited after the bloom for legibility - with an adaptive quality governor (HIGH / BALANCED / ECO, hysteresis-based) and a hard fallback to direct rendering.
• Crash-safe saves: budgeted ~0.75 ms/frame capture (aborted cleanly if the revision changes mid-capture), daemon worker with coalesced autosaves, temp-file + atomic rename, and monotone commit tokens so a stale write can never clobber a newer commit.

All of it is pinned down by 71 JUnit 5 test files covering revisions, memoization, cycles, undo/redo, spatial culling, save ordering/coalescence and screen lifecycle.

What I Learned

1. Own the boundary between logic and pixels. The snapshot API is the single decision I’d make first in any real-time editor: it made the simulation trivially unit-testable and the renderer a dumb projection.
2. Invalidate narrowly. Three small revision counters bought more frame-time headroom than any micro-optimization - the index, the caches and the simulation each rebuild only when they truly must.
3. Async I/O needs ordering guarantees, not just threads. The monotone token coordinator is 100 lines that made “never lose the newest save” a provable property instead of a hope.
4. Content as data. Once challenges and text became JSON, the campaign could grow from 10 to 89 challenges without a single Java change - and localization became a catalog, not a refactor.
5. Budget everything that touches the frame. Save capture, camera drags, index rebuilds - if it can run for 2 ms today, budget it for a 200-component circuit tomorrow.

Why This Project Matters

CircuitSim is the deepest solo systems project I’ve done: a deterministic simulation engine with real semantics (tri-state, feedback, sequential state), a full editor architecture (commands, revisions, spatial indexing), a production graphics pipeline on a constrained API (GLES2), a crash-safe persistence layer, and an entire authored game experience on top - ending with the player building and running a 4-bit CPU from first principles.

It demonstrates the full arc from formal core (the simulation) to shipped product (the campaign, i18n, adaptive rendering), with a test suite that keeps every layer honest.