If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/SebLague/Digital-Logic-Sim shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 12mo ago

• Last commit 12mo ago
• 5 active contributors
• MIT licensed
• Tests present
• ⚠ Slowing — last commit 12mo ago
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live SebLague/Digital-Logic-Sim repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/SebLague/Digital-Logic-Sim.

What it runs against: a local clone of SebLague/Digital-Logic-Sim — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in SebLague/Digital-Logic-Sim | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 385 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of SebLague/Digital-Logic-Sim. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/SebLague/Digital-Logic-Sim.git
#   cd Digital-Logic-Sim
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of SebLague/Digital-Logic-Sim and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "SebLague/Digital-Logic-Sim(\\.git)?\\b" \\
  && ok "origin remote is SebLague/Digital-Logic-Sim" \\
  || miss "origin remote is not SebLague/Digital-Logic-Sim (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Assets/Scripts/Description/Types/ChipDescription.cs" \\
  && ok "Assets/Scripts/Description/Types/ChipDescription.cs" \\
  || miss "missing critical file: Assets/Scripts/Description/Types/ChipDescription.cs"
test -f "Assets/Scripts/Description/Types/ProjectDescription.cs" \\
  && ok "Assets/Scripts/Description/Types/ProjectDescription.cs" \\
  || miss "missing critical file: Assets/Scripts/Description/Types/ProjectDescription.cs"
test -f "Assets/Scripts/Description/Serialization/Serializer.cs" \\
  && ok "Assets/Scripts/Description/Serialization/Serializer.cs" \\
  || miss "missing critical file: Assets/Scripts/Description/Serialization/Serializer.cs"
test -f "Assets/Scripts/DLS.asmdef" \\
  && ok "Assets/Scripts/DLS.asmdef" \\
  || miss "missing critical file: Assets/Scripts/DLS.asmdef"
test -f "Assets/Build/DLS.unity" \\
  && ok "Assets/Build/DLS.unity" \\
  || miss "missing critical file: Assets/Build/DLS.unity"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 385 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~355d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/SebLague/Digital-Logic-Sim"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A minimalist digital logic simulator built in Unity (C#) that lets users design and test circuits by connecting logic gates, adders, and other chips visually. It's the reference implementation for Sebastian Lague's educational video series on how computers work, supporting both interactive play and programmatic chip definitions via a custom chip format. Standard Unity project structure: Assets/Scripts/ contains the core engine (DLS.asmdef), Assets/Build/ holds the production scene (DLS.unity), and Assets/Dev/ isolates video tools and experimental code (DLS.Dev.asmdef) to avoid polluting builds. Custom chip data likely lives outside the repo or in a save format handled by DevSaveDataRefactor.cs.

Computer science students and self-taught learners who want to understand CPU architecture from first principles by building circuits interactively; also video creators and educators teaching digital logic concepts without heavy industrial CAD tools.

Actively maintained educational project with a shipped product on itch.io. The codebase is well-organized into modular assemblies (DLS.asmdef, DLS.Dev.asmdef) and has clear scene structure, but is tightly coupled to Unity's engine—treat it as production-ready for educational use, not as a portable library. No visible CI/CD pipeline or automated test suite in the file list.

Single-author maintenance (SebLague) means feature requests may stall; the repo explicitly prioritizes bug fixes and UX over new chip contributions, and mod support is explicitly unplanned. Tightly dependent on Unity (specific version unknown from file list) and ShaderLab, making it non-portable. No public issue tracker visible in file list, so community friction points are opaque.

The file Assets/Dev/SaveRefac/DevSaveDataRefactor.cs suggests a recent or in-progress refactor of save/load serialization. Video tooling in Assets/Dev/VidTools (InputRecorder, VidTools, InputPlayback) implies active content creation. No specific commit-level data is visible, but the organized dev tooling suggests regular maintenance.

Check README for instructions.

Daily commands: Open the project in Unity 2019.3+. In the editor, press Play on Assets/Build/DLS.unity for a release-like build, or Assets/Dev/VidTools/Scenes/Dev.unity for full dev tooling. Export via File > Build Settings > Build.

• Assets/Scripts/Description/Types/ChipDescription.cs — Core data model for chip definitions; every logic component in the simulator is described by this structure.
• Assets/Scripts/Description/Types/ProjectDescription.cs — Root project container holding all chips and circuit definitions; required to understand project persistence and composition.
• Assets/Scripts/Description/Serialization/Serializer.cs — Handles JSON serialization/deserialization of all circuit and chip data; critical for load/save functionality.
• Assets/Scripts/DLS.asmdef — Main assembly definition that organizes the core simulator codebase; defines dependencies and compilation boundaries.
• Assets/Build/DLS.unity — Main scene for the built application; entry point for the runtime simulator.
• Assets/Scripts/Description/Helpers/ChipTypeHelper.cs — Utility for resolving and managing chip types; bridges between chip descriptions and runtime instantiation.
• Assets/Scripts/Description/Serialization/UnsavedChangeDetector.cs — Tracks unsaved changes in the project; essential for UX feedback and preventing data loss.

• ProjectDescription (C# serializable class, Newtonsoft.Json) — Root container holding all chips, project metadata, and app settings; single source of truth for a circuit
  • Failure mode: Corrupted JSON or missing required fields causes deserialization failure; unsaved changes lost
• ChipDescription (C# serializable class, PinAddress, ChipTypes enum) — Metadata for a single chip instance: type, position, pin layout, internal wiring; does not contain runtime state
  • Failure mode: Invalid pin count or missing type enum causes instantiation error
• Serializer (Newtonsoft.Json, System.IO) — Marshals ProjectDescription to/from JSON files; bridges data layer and persistence
  • Failure mode: Version mismatch or unknown chip type causes deserialization exception; file I/O errors prevent save
• ChipTypeHelper (C# enums, reflection or switch statements) — Resolves ChipTypes enum to instantiation metadata (pin layout, display info); lookup table between type and behavior
  • Failure mode: Missing type in helper causes null reference when creating new chip; wrong pin count breaks circuit
• UnsavedChangeDetector (C# event system,) — Tracks mutations to ProjectDescription; signals UI to show unsaved indicator and prompt on quit

Add a new built-in chip type

1. Add a new enum value in ChipTypes.cs for the new chip (e.g., AND, OR, XOR) (Assets/Scripts/Description/Types/SubTypes/ChipTypes.cs)
2. Update ChipTypeHelper.cs to map the new enum to instantiation logic and metadata (Assets/Scripts/Description/Helpers/ChipTypeHelper.cs)
3. Define pin layout and behavior in the corresponding chip class (check for runtime implementations in Scripts folder)
4. Test serialization by creating a ChipDescription with the new type and verifying Serializer.cs handles it

Modify project save/load format

1. Update the relevant data type (ChipDescription, ProjectDescription, or PinDescription) (Assets/Scripts/Description/Types/ProjectDescription.cs)
2. Verify Serializer.cs correctly serializes the new fields using Newtonsoft.Json (Assets/Scripts/Description/Serialization/Serializer.cs)
3. Add a migration routine in DevSaveDataRefactor.cs if backward compatibility is needed (Assets/Dev/SaveRefac/DevSaveDataRefactor.cs)
4. Test round-trip serialization to ensure data integrity

Add user-facing application settings

1. Add new fields to AppSettings.cs (Assets/Scripts/Description/Types/AppSettings.cs)
2. Ensure Serializer.cs includes AppSettings in save/load logic (Assets/Scripts/Description/Serialization/Serializer.cs)
3. Create UI bindings in the main scene (Assets/Build/DLS.unity) to expose settings
4. Track changes in UnsavedChangeDetector.cs to prompt save when settings are modified (Assets/Scripts/Description/Serialization/UnsavedChangeDetector.cs)

• Unity (C#) — Educational game engine for interactive circuit visualization and simulation; enables cross-platform builds (Windows, Mac, Web, etc.)
• Newtonsoft.Json — Industry-standard JSON serialization library with AOT support for multiple platforms; decouples data models from serialization concerns
• Assembly definitions (.asmdef) — Organizes code into DLS.asmdef (core) and DLS.Description.asmdef (data layer) for faster compilation and clear dependency boundaries

• Data-driven architecture with serializable POCOs (ChipDescription, ProjectDescription)

  • Why: Simplifies save/load logic and allows user projects to be human-readable JSON files
  • Consequence: Runtime instantiation logic is separated from data definitions, requiring ChipTypeHelper to map enums to behavior

• Monolithic scene (DLS.unity) rather than modular subscenes

  • Why: Easier single-entry-point for end users building circuits
  • Consequence: Scaling to complex projects with many chips may require scene streaming or optimization

• UnsavedChangeDetector as separate concern from Serializer

  • Why: Decouples dirty-flag logic from persistence, improving testability
  • Consequence: Changes must be tracked in two places (data mutation + detector notification)

• Real-time HDL synthesis or FPGA deployment
• Multi-user collaborative editing
• 3D circuit visualization (2D only)
• Scripting/modding API (mentioned as future work in README)

Unity version is not specified in the file list—check Assets/ProjectSettings/ProjectVersion.txt before cloning. The Dev and Build scenes use different assemblies (DLS.Dev vs DLS), so uncommenting Dev code in Build may cause assembly conflicts. ShaderLab shaders require compilation at editor time; no indication of fallback shaders for unsupported platforms. Save format appears to be custom and undergoing refactor—old save files may not load on the latest version.

• Combinational vs. Sequential Logic — DLS chips are either combinational (gates, adders, MUX—output depends only on current input) or sequential (flip-flops, RAM—output depends on state history). Understanding this distinction is essential to avoid building broken circuits.
• Wire Bundling / Bus Representation — Logic simulators represent multi-bit data (e.g., 16-bit addresses) as bundled wires to avoid visual clutter. DLS likely uses bus notation to render and evaluate groups of signals as single entities, critical for reading/creating complex chips.
• Chip Abstraction and Composability — DLS allows users to define custom chips (e.g., a full adder built from AND/OR/XOR gates) and reuse them as black boxes in larger circuits. This abstraction is fundamental to scaling from gate-level to CPU-level designs.
• Propagation Delay and Timing — Real logic gates introduce delay; circuits may exhibit glitches or race conditions if timing is not managed. DLS must model or abstract propagation delay to produce realistic behavior and teach users about timing closure.
• Immediate Mode Rendering (ShaderLab/GPU-based UI) — DLS uses ShaderLab for custom circuit visualization (wires, gates, grid). Understanding immediate-mode vs. retained-mode rendering helps optimize performance and extend the visual editor.
• Serialization and Save Format Design — The DevSaveDataRefactor.cs refactor is active, indicating evolving circuit persistence. Understanding how wires, pins, and chip instances are serialized is critical for supporting new features (undo/redo, sharing, versioning).
• Event-Driven Simulation vs. Clock-Driven Simulation — Logic simulators can update gates only when inputs change (event-driven, fast) or on every clock cycle (clock-driven, deterministic). DLS's choice affects performance and accuracy; understanding this is key to debugging unexpected behavior.

• LogisimEvolution/logisim-evolution — Desktop logic simulator with a broader feature set (RAM, clocks, ROM) and Java-based portability; direct competitor solving the same pedagogical problem at higher complexity.
• 01-edu/digital — Lightweight open-source digital logic simulator with emphasis on simplicity and teaching; shares the same edu-first philosophy and visual circuit design paradigm as DLS.
• DigitalJS/digitaljs — Browser-based JavaScript logic simulator that runs in the cloud without desktop installation; alternative delivery model for the same learner audience.
• SebLague/Exploring-How-Computers-Work — The official companion video series repo; likely contains circuit designs, assets, and documented examples referenced in video episodes.
• Game-Developers-Academy/Digital-Logic-Simulator — Educational fork or tutorial repo that may provide step-by-step guides and custom chip examples for newcomers to the DLS engine.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for chip serialization and deserialization

The repo contains a Newtonsoft JSON serialization framework (Assets/Scripts/Description/Serialization/Newtonsoft/) but there are no visible test files for chip save/load functionality. Given the complexity of the save system (evidenced by DevSaveDataRefactor.cs), adding tests would catch regressions early and improve maintainability. This aligns with the maintainer's stated preference for 'bug fixes' and 'performance/ux improvements'.

• [ ] Create Assets/Scripts/Description/Tests/ directory with assembly definition file
• [ ] Add unit tests for ChipTypeHelper.cs serialization edge cases (custom chips, built-in chips, invalid types)
• [ ] Add integration tests for round-trip serialization (serialize → deserialize → verify equivalence)
• [ ] Test error handling for corrupted/malformed save data files
• [ ] Document test coverage in a TEST.md file

Add GitHub Actions workflow for build validation and test execution

The repo is a Unity project with assembly definitions (DLS.asmdef, DLS.Dev.asmdef, DLS.Description.asmdef) indicating a modular structure, but there's no visible CI pipeline. A GitHub Action to validate builds and run tests would catch compatibility issues before merging, reducing maintenance burden on the maintainer. Unity Cloud Build integrations or Unity automated test runners could catch regressions early.

• [ ] Create .github/workflows/validate-build.yml that uses unity-builder action
• [ ] Configure workflow to run on all PRs targeting main branch
• [ ] Add test execution step using Unity's automated test runner for Assets/Scripts/Description/Tests/
• [ ] Document supported Unity versions in CONTRIBUTING.md or CI workflow file
• [ ] Add build status badge to README.md

Refactor VidTools development code into separate package with clear documentation

Assets/Dev/VidTools/ contains video recording/input playback utilities that are separate from core simulation logic but lack documentation on their purpose or usage. The maintainer likely uses these internally for creating educational videos. Extracting this into a documented optional package with clear README would help contributors understand the codebase structure and enable selective inclusion/exclusion in builds.

• [ ] Create Assets/Dev/VidTools/README.md documenting purpose, usage, and scenes (reference existing Scene files: Dev.unity, Vid_Name.unity)
• [ ] Document the InputRecorder → InputPlayback → VidInputController flow for video production
• [ ] Create Assets/Dev/CONTRIBUTING.md explaining that VidTools are internal dev utilities, not part of core PR review expectations
• [ ] Consider extracting VidTools into a separate assembly definition (VidTools.asmdef) if not already modular to reduce core build dependencies

• Add unit tests for chip evaluation logic: Assets/Scripts/ likely lacks test coverage for core gate operations (AND, OR, NOT, adders). Create Assets/Scripts/Tests/ with Editor test assemblies using Unity's Test Framework, starting with a simple gate truth table validator.
• Document the custom chip file format: DevSaveDataRefactor.cs implies a circuit/chip serialization format exists, but it's not documented in README or code comments. Write a brief spec in Markdown describing the wire, pin, and chip syntax, with 2–3 worked examples.
• Add mobile touch input support to VidInputController: The input abstraction exists but appears keyboard/mouse-only. Extend Assets/Dev/VidTools/InputRecording/VidInputController.cs to detect and map touch events (dragging, tapping) for iPad/Android use.

This is a Unity-based educational project with moderate security posture. The primary concerns are dependency management practices (Newtonsoft.Json versions not explicitly tracked), inclusion of development/test code in the repository, and absence of formal security policies. The codebase shows no obvious code injection risks, hardcoded secrets, or exposed credentials. As an open-source educational project, the security risk is relatively low, but dependency tracking and build configuration separation should be improved. No Docker/infrastructure security issues detected.

• Medium · Outdated Newtonsoft.Json Dependency — Assets/Scripts/Description/Serialization/Newtonsoft/Runtime/. The codebase includes Newtonsoft.Json (JSON.NET) library with potential version concerns. The presence of multiple compiled DLL files without visible version information or lock files suggests dependency management may not be strictly controlled. This could lead to using outdated versions with known vulnerabilities. Fix: Implement a package-lock or dependency manifest file. Use NuGet package manager to explicitly specify and lock dependency versions. Regularly audit dependencies for CVEs using tools like OWASP Dependency-Check or Snyk.
• Low · Development Tools in Production Codebase — Assets/Dev/. Development-specific code and video tools are included in the main Assets directory (Assets/Dev/VidTools, Assets/Dev/SaveRefac). This increases the attack surface and could expose development methodologies or test data if the build is compromised. Fix: Separate development and production assets. Exclude development directories from production builds using build configurations or .gitignore stricter rules. Ensure dev assemblies are not included in release builds.
• Low · Missing Security Configuration Documentation — Repository root. No visible security policy, vulnerability disclosure process, or security guidelines are apparent in the README or file structure. The project accepts pull requests but lacks documented security review procedures. Fix: Create a SECURITY.md file with vulnerability disclosure policy. Implement a security review process for pull requests. Consider adding a CONTRIBUTORS.md with security guidelines.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.