Interactive, real-time circuit simulator built with Java Swing. Design circuits on a grid, wire them up, and watch the simulation update live (analog voltages/currents + basic digital logic gates).

CircuitSim is designed as a “sandbox” editor: you place components from a palette, connect them with wires, then the solver continuously recomputes values as you move/rotate/edit the circuit.

Current version: 1.1.7

• Analog simulation: continuous DC-style solver for voltages/currents with short-circuit detection.
• Digital logic simulation: built-in logic gates (NAND/AND/OR/XOR/NOT) driving wires as 0V/5V signals.
• Custom components: dedicated editor with input/output ports, nesting, and local + temporary libraries.
• Editor UX: grid-snapped placement, multi-select, rotate, resize, pan, zoom, context menus.
• Component + wire palettes: grouped components, drag-and-drop placement, selectable wire colors.
• Properties panel: edit component parameters and titles in real time.
• Persistence: save/load JSON boards, autosave, undo/redo, temp custom-component mode.

• JDK 21+ for development and packaging

If you're using VS Code, point the Java extension at a JDK 21 install (workspace defaults live in .vscode/settings.json).

For packaged releases, end users do not need Java installed. The Windows and Linux packages can bundle a private runtime inside the app.

Run the prebuilt JAR

java -jar dist/CircuitSim.jar

Run from source

javac --release 21 -d out $(find src/main/java -name "*.java")
java -cp out circuitsim.CircuitSim

Or use the helper script on Linux/macOS:

./scripts/run-dev.sh

Build a runnable JAR

./scripts/build-jar.sh

The build scripts read the release version from build/version.txt and generate both dist/CircuitSim.jar and dist/CircuitSim-<version>.jar.

CircuitSim can be packaged for Windows and Linux with a bundled Java runtime so users do not need to install a JDK or JRE.

Important

• Packaging is platform-specific: build Windows packages on Windows and Linux packages on Linux.
• jpackage is required for packaged releases. A full JDK 21 is needed on the packaging machine.
• The packaged app uses its own internal runtime/ directory generated by jpackage.
• The Android Studio bundled runtime usually does not include jpackage; if that is your current JAVA_HOME, point JAVA_HOME to a full JDK 21 before packaging.

Windows

Windows installer builds (--type exe) require WiX Toolset v3.x on the packaging machine so candle.exe and light.exe are available on PATH. The packaged launcher uses packaging/circuitsim.ico when that asset is present. The installer also uses a stable Windows upgrade UUID, so newer installers can replace older installs instead of requiring a manual uninstall. Bump build/version.txt before creating the new installer. Windows Start menu shortcuts are grouped under BlazingHotCode.

Build an app image plus installer .exe:

powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1

Build only the portable app image:

powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1 -Type app-image

If you only want to verify the jar build on a machine without jpackage on PATH:

powershell -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1 -SkipJPackage

Linux

The packaged launcher uses packaging/circuitsim.png when that asset is present.

Build the full Linux set: portable app image, distro-neutral .tar.gz, .deb, and .rpm:

./scripts/package-linux.sh

Build only the portable app image directory:

./scripts/package-linux.sh --type app-image

Build only the distro-neutral portable archive:

./scripts/package-linux.sh --type portable

Build only the Debian package:

./scripts/package-linux.sh --type deb

Build only the RPM package:

./scripts/package-linux.sh --type rpm

Build the Flatpak bundle:

./scripts/package-flatpak.sh

If you only want to verify the jar build on a machine without jpackage installed:

./scripts/package-linux.sh --skip-jpackage

Linux package notes

• The visible app name stays CircuitSim.
• The Linux package identifier uses the distro-friendly name circuitsim.
• ./scripts/package-linux.sh now defaults to the broadest Linux output set: app image + .tar.gz + .deb + .rpm.
• Linux package filenames now include architecture-specific suffixes where needed so release assets clearly distinguish x86_64 and arm64 builds.
• The .tar.gz archive is the closest thing to an all-distro option for a given CPU architecture because it just extracts and runs with the bundled runtime.
• Flatpak support is included through scripts/package-flatpak.sh, which builds io.github.BlazingHotCode.CircuitSim and bundles its own Java runtime inside the Flatpak.
• Building .deb packages usually requires fakeroot, and .rpm packages require rpm/rpmbuild, to be available on the build machine.
• Building the Flatpak bundle requires flatpak, flatpak-builder, and the org.freedesktop 24.08 runtime/sdk plus the openjdk21 SDK extension.

• Keep using a normal JDK 21 install for development.
• Dev builds do not require packaging, installers, or bundled runtimes.
• Packaged releases are an extra release step for end users, not a replacement for the source-based workflow.

• GitHub Actions now builds bundled-runtime packages on both Windows and Linux when you push to main or trigger the workflow manually.
• The workflow file is /.github/workflows/package.yml.
• Uploaded artifacts include:
  • Windows: installer .exe plus portable app image
  • Linux: x86_64 and arm64 variants of .deb, .rpm, Flatpak .flatpak, portable .tar.gz, plus portable app image
• Tagged releases use /.github/workflows/release.yml to publish a GitHub Release with Windows and Linux downloads attached.
• The release body uses release-notes/<version>.md when present.
• Use release-notes/TEMPLATE.md as the starting point for new release notes, including install/update snippets for Windows, .deb, .rpm, portable .tar.gz, and Flatpak users.
• packaging/flatpak/io.github.BlazingHotCode.CircuitSim.flathub.yml is the Flathub-ready manifest; it builds from a pinned GitHub source archive for the intended upstream commit.
• After running ./scripts/build-jar.sh, use ./scripts/update-flathub-manifest.sh to refresh the Flathub manifest URL and checksum for the current version.
• See packaging/flatpak/FLATHUB.md for the exact files and validation commands to use in your Flathub submission PR.
• To publish a release, update build/version.txt, commit the release changes, then push a matching tag such as v1.1.3.

• Packaging icons live in packaging/circuitsim.ico and packaging/circuitsim.png.
• If you want to regenerate the default icon set on Windows, run powershell -ExecutionPolicy Bypass -File .\scripts\generate-packaging-assets.ps1.

1. Open the component bar (Tab) and pick a component group.
2. Click a component to place it, or drag it from the dropdown onto the canvas.
3. Click a connection point and drag to another point to create a wire.
4. Use the properties panel (right side) to edit values like resistance, voltage, and labels.
5. Save your circuit with Ctrl+S and load with Ctrl+O.

Mouse

• Left click: select components/wires.
• Drag: move components, wires, or a multi-selection.
• Shift + drag component: move the component without dragging attached wires.
• Drag empty space: box-select multiple items.
• Right drag: pan the view.
• Right click: context menu (add/delete, wire data toggle).
• Double click wire: delete wire.
• Double click custom component: open its editor.
• Drag resize handle: resize component.
• Click rotate handle or press R: rotate selection.
• Ctrl + mouse wheel: zoom in/out.
• Shift while starting a wire: lock wire creation and finish with a click.

Keyboard

• Ctrl+S: save board (JSON).
• Ctrl+O: load board (JSON).
• Ctrl+Z: undo.
• Ctrl+Shift+Z: redo.
• Delete/Backspace: delete selection.
• Arrow keys: move selection by one grid step.
• R: rotate selection.
• Ctrl++ / Ctrl+-: zoom in/out.
• F1: reset view.
• F2: clear board.
• Tab: toggle component bar.

Built-in groups

• Sources: Battery, Source (toggleable).
• Logic: NAND, AND, OR, XOR, NOT.
• Passive: Resistor.
• Meters: Voltmeter, Ammeter.
• Controls: Switch.
• Reference: Ground.

Custom-component editor

• Ports: Input Port, Output Port (used for defining a custom component’s interface).

Custom components

• Create, edit, and delete custom components from the Custom group.
• Editor mode adds Input/Output ports for defining custom interfaces.
• Custom components can be nested and reused like built-ins.

• Logic gates output either ~0V (LOW) or ~5V (HIGH) with a ~2.5V threshold.
• Gate outputs drive connected wires; those wires are marked as “logic powered” internally so logic can propagate even when the analog solver would otherwise show ~0 current.
• Logic inputs enforce a single-wire-per-input connection rule to prevent ambiguous fan-in at the pin.

• Wire endpoints placed on a component connection point are attached and will follow that point when the component moves/resizes/rotates.
• Hold Shift while dragging a component to move it without pulling attached wire endpoints.

When you load a board that includes custom components, CircuitSim asks where to store them:

• Add to Local: saves definitions in your local library.
• Use Temp: keeps definitions in a temporary library until you exit temp mode.

Use the "Go Back To Save" button to exit temp mode and return to local storage.

Board files

• Saved/loaded as JSON via the file chooser.
• Example boards live in saves/ (try loading saves/1.json or saves/2.json).

Autosave

• Windows: %LOCALAPPDATA%\CircuitSimData\autosave.json
• macOS: ~/Library/Application Support/CircuitSimData/autosave.json
• Linux: ~/.local/share/CircuitSimData/autosave.json

Custom component storage

• Local: .../CircuitSimData/CustomComponents
• Temp mode: .../CircuitSimData/TempData

• src/main/java/circuitsim/ui: Swing UI (canvas, palettes, properties panel, custom editor UI).
• src/main/java/circuitsim/components: Component types (electrical, instruments, wiring, logic, ports).
• src/main/java/circuitsim/physics: Simulation code (analog solver + logic update pass).
• src/main/java/circuitsim/io and src/main/java/circuitsim/custom: JSON persistence + custom-component library.

Apache License 2.0. See LICENSE.