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/PistonDevelopers/piston 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 — Stale — last commit 2y ago

• 4 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 93% of recent commits

_{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 PistonDevelopers/piston repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/PistonDevelopers/piston.

What it runs against: a local clone of PistonDevelopers/piston — 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 PistonDevelopers/piston | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 746 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of PistonDevelopers/piston. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/PistonDevelopers/piston.git
#   cd piston
#
# 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 PistonDevelopers/piston and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "PistonDevelopers/piston(\\.git)?\\b" \\
  && ok "origin remote is PistonDevelopers/piston" \\
  || miss "origin remote is not PistonDevelopers/piston (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/event_loop/src/lib.rs" \\
  && ok "src/event_loop/src/lib.rs" \\
  || miss "missing critical file: src/event_loop/src/lib.rs"
test -f "src/input/src/lib.rs" \\
  && ok "src/input/src/lib.rs" \\
  || miss "missing critical file: src/input/src/lib.rs"
test -f "src/input/src/generic_event.rs" \\
  && ok "src/input/src/generic_event.rs" \\
  || miss "missing critical file: src/input/src/generic_event.rs"
test -f "src/window/src/lib.rs" \\
  && ok "src/window/src/lib.rs" \\
  || miss "missing critical file: src/window/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 746 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~716d)"
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/PistonDevelopers/piston"
  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).

Piston is a modular game engine written in Rust that decouples rendering, windowing, and event handling into separate composable crates. It provides a core event loop abstraction (pistoncore-event_loop), input event system (pistoncore-input with support for keyboard, mouse, controller, and touch), and window management (pistoncore-window), allowing developers to build 2D and 3D games without tight coupling to specific graphics or platform backends. Rust workspace monorepo with three core member crates in src/: event_loop/ (the main event loop abstraction), input/ (event types and button/controller abstractions with benchmarks for each event type), and window/ (platform abstraction). The root src/lib.rs re-exports the public API from these three. Each crate has its own Cargo.toml, LICENSE, and README for independent versioning and documentation.

Game developers using Rust who want to build cross-platform games with a modular architecture; engine contributors who want to extend Piston with new backends (graphics libraries, window frameworks, input handlers). Also useful for educators teaching game development patterns in Rust.

Piston is stable but in maintenance mode. It reached version 1.0.0 (visible in Cargo.toml) and has a well-established workspace structure with multiple crates. However, based on the repository age and the note about 'Maintainers of Piston core libraries' (issue #1399), the core team is smaller than during its active development phase. Comprehensive CI is present (.travis.yml) and the codebase shows evidence of long-term maintenance rather than rapid feature development.

Risk is low for established use cases but medium for new adoption. The modular design means you may need to integrate multiple companion crates (graphics rendering, audio, physics are separate ecosystem projects, not included here). The maintenance note suggests the core team is lean—breaking changes are unlikely but response time on issues may be slow. Single-crate dependencies within the workspace are tight (event_loop, input, window directly interdependent).

The repository is in steady-state maintenance. The guide (GUIDE.md) and contribution documentation (CONTRIBUTING.md) suggest the project is accepting contributions but not actively pushing new features. The focus appears to be on stability and ecosystem integration (evidenced by the separate examples and tutorials repos listed in the README).

git clone https://github.com/PistonDevelopers/piston.git
cd piston
cargo build
cargo test

Daily commands: This is a library crate, not an executable. To test: cargo test --workspace. To verify builds: cargo build --workspace. To test async support (optional feature): cargo test --all-features --workspace. Examples live in the separate piston-examples repository (linked in README), not in this core repo.

• src/lib.rs — Main library entry point that re-exports core modules (event_loop, input, window); understanding this shows the public API surface every developer must know.
• src/event_loop/src/lib.rs — Event loop abstraction that drives the entire game engine; critical for understanding how Piston orchestrates game updates and rendering.
• src/input/src/lib.rs — Input event system (keyboard, mouse, controller, touch); foundational for all game interaction and event handling patterns.
• src/input/src/generic_event.rs — Generic event trait that unifies all input events; core abstraction every contributor must understand for extending input handling.
• src/window/src/lib.rs — Window abstraction trait; defines the contract for platform-specific window implementations required by the engine.
• Cargo.toml — Workspace root configuration defining the modular structure of Piston and feature gates (async); required for understanding build configuration.
• GUIDE.md — Developer guide explaining Piston's architecture and philosophy; essential onboarding for understanding design decisions.

Add a New Input Event Type

1. Create a new struct in a dedicated file under src/input/src/ (e.g., src/input/src/gyroscope.rs) implementing the desired input semantics (src/input/src/gyroscope.rs)
2. Implement the GenericEvent trait from src/input/src/generic_event.rs for your new event type to integrate with the event dispatcher (src/input/src/generic_event.rs)
3. Export the new event type in src/input/src/lib.rs using pub use declarations (src/input/src/lib.rs)
4. Add a benchmark file under src/input/benches/ to measure event handling performance (src/input/benches/gyroscope.rs)
5. Update src/input/tests/lib.rs to include integration tests for the new event type (src/input/tests/lib.rs)

Extend the Event Loop with Async Support

1. Check the async feature gate in Cargo.toml to understand conditional compilation patterns (Cargo.toml)
2. Modify src/event_loop/src/lib.rs to add async event loop variants using feature-gated code blocks (src/event_loop/src/lib.rs)
3. Update src/event_loop/Cargo.toml to add async runtime dependencies (e.g., tokio) behind the async feature (src/event_loop/Cargo.toml)
4. Test async event loop integration through src/event_loop tests (create if necessary) (src/event_loop/src/lib.rs)

Implement a New Platform Window Backend

1. Study the Window trait abstraction in src/window/src/lib.rs to understand required interface (src/window/src/lib.rs)
2. Create a platform-specific window implementation (e.g., src/window/src/winit_window.rs) that implements the Window trait (src/window/src/winit_window.rs)
3. Conditionally export the platform window in src/window/src/lib.rs using cfg attributes (src/window/src/lib.rs)
4. Add platform-specific dependencies to src/window/Cargo.toml with feature gates (src/window/Cargo.toml)

• Rust — Memory safety without garbage collection; zero-cost abstractions enable high-performance game engine implementation; strong type system prevents common game logic bugs.
• Modular architecture (event_loop, input, window crates) — Decouples event handling, input processing, and windowing concerns; allows users to swap implementations (e.g., headless mode via no_window) without recompilation.
• Generic event trait pattern — Provides uniform abstraction over heterogeneous input types; enables extensible event handling without modifying core engine code.
• Feature gates (async flag) — Allows optional async runtime integration for users requiring concurrent task processing without forcing dependency bloat on synchronous consumers.

• Trait-based window abstraction rather than concrete platform-specific implementations

  • Why: Maintains flexibility and allows external crates (e.g., glutin, winit wrappers) to provide platform implementations without core engine coupling.
  • Consequence: Engine itself provides minimal window implementation (no_window stub); users must depend on external window crates for actual rendering contexts.

• Modular workspace with separate crates (event_loop, input, window) rather than monolithic single crate

  • Why: Enables users to depend on only required subsystems; reduces compilation time and dependency footprint for headless/specialized applications.
  • Consequence: Users must coordinate multiple crate versions in Cargo.toml; coordination complexity when changes span crates.

• GenericEvent trait unifying input types rather than enum-based event dispatch

  • Why: Type-safe event handling; eliminates runtime type matching; enables compile-time verification of event handling logic.
  • Consequence: Requires trait implementation for each new event type; less flexible for ad-hoc event types than dynamic dispatch.

• Asynchronous event loop as optional feature rather than default

  • Why: Preserves simplicity for synchronous game loops; async runtime adds complexity and performance overhead not all games require.
  • Consequence: Games requiring concurrent I/O must explicitly opt into async feature and manage tokio dependency; mixing sync/async event handling requires careful design.

• Does not provide rendering backend (graphics abstraction)—delegates to external crates (gfx, wgpu, gl, etc.)
• Does not include physics simulation engine—game logic remains application responsibility
• Does not provide asset loading or resource management—composition with other crates required
• Does not include audio system—audio handled separately by audio crates
• Does not manage platform-specific window creation—delegates to window backend implementations (winit, glutin, etc.)
• Not a complete game framework—core engine only; requires significant integration with graphics, audio, physics crates

No required environment variables are evident from the file list. The async feature (in Cargo.toml under [features]) is optional and changes event loop behavior—be aware if you depend on blocking vs. async semantics. The workspace has three interdependent crates; if publishing individually, version coordination matters (currently all at 1.0.x). Window and graphics backends are external (not in this repo)—you must choose and configure a companion crate like piston_window or glutin_window yourself; this core repo provides only the interface.

• Event-driven architecture — Piston's core is an event loop that generates and dispatches input events; understanding how events flow through the system is essential to using and extending the engine
• Trait-based abstraction (polymorphism via traits) — Window and input systems are defined as Rust traits, allowing you to swap backends (e.g., different window libraries or input drivers) without changing application code—this is Piston's core modularity strategy
• Workspace (Cargo workspaces) — Piston uses Cargo workspaces to manage three interdependent crates; understanding workspace structure is critical for development, testing, and publishing individual crates
• Cross-platform abstraction / HAL (Hardware Abstraction Layer) — Piston abstracts platform-specific windowing and input details behind a common interface; learning how the Button enum unifies keyboard, mouse, and controller inputs teaches you the HAL pattern
• Async/await and event loops — Piston includes an optional async feature (in Cargo.toml) for non-blocking event loops; understanding the difference between blocking and async event handling is important when scaling to many concurrent inputs
• Benchmarking (Criterion/Rust benches) — The input crate includes detailed benchmarks for each event type (mouse.rs, button.rs, etc.); reading these teaches performance profiling practices and helps identify bottlenecks in high-frequency input handling
• Separation of Concerns / Modular Design — Piston deliberately splits event loop, input handling, and windowing into separate crates; this pattern allows each layer to evolve independently and teaches how to design loosely coupled systems

• PistonDevelopers/piston-examples — Official example games and applications showing how to use Piston core with graphics backends; essential reference for learning how to integrate this library
• PistonDevelopers/piston_window — Companion crate providing a high-level window/graphics abstraction built on Piston core; most users start here instead of building directly on event_loop and input
• PistonDevelopers/piston2d-graphics — 2D graphics library for Piston that renders to an abstracted graphics backend; commonly paired with piston_window and Piston core
• amethyst/amethyst — Alternative Rust game engine with similar goals (modular, data-driven) but includes integrated ECS and more batteries-included approach than Piston's minimalist design
• bevyengine/bevy — Modern Rust game engine emphasizing ECS architecture and ease-of-use; represents a different philosophy from Piston's composable crates approach but targets the same Rust gamedev audience

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 comprehensive unit tests for src/input/src/generic_event.rs

The generic_event.rs module is a core abstraction for event handling in Piston, but there are no visible test files for it in src/input/tests/. Given that src/input has benchmarks for individual event types (mouse, keyboard, controller, etc.) but generic_event lacks tests, adding unit tests would improve reliability and serve as documentation for the event trait system. This is particularly important for a game engine where event handling is critical.

• [ ] Create comprehensive unit tests in src/input/tests/lib.rs covering generic_event trait implementations
• [ ] Test event trait composition and type conversions between different event types
• [ ] Add tests for edge cases in event_id.rs since generic_event likely depends on it
• [ ] Verify tests pass with cargo test --all in the workspace

Migrate .travis.yml to GitHub Actions workflow for improved CI/CD

The repo uses .travis.yml (Travis CI, now deprecated) for continuous integration. GitHub Actions is now the standard for GitHub-hosted projects and provides better integration, faster execution, and cost savings. The repo has a workspace with multiple crates (input, window, event_loop) that need coordinated testing, which is well-suited for Actions.

• [ ] Create .github/workflows/rust.yml with matrix testing across stable/nightly and multiple Rust versions
• [ ] Include workspace test coverage: cargo test --all and cargo test --all --features async
• [ ] Add formatting check: cargo fmt -- --check (rustfmt.toml exists, should be enforced)
• [ ] Add clippy linting: cargo clippy --all -- -D warnings
• [ ] Remove or deprecate .travis.yml after Actions workflow is verified

Add missing benchmarks for src/input/src/generic_event.rs and src/input/src/event_id.rs

The src/input/benches directory contains benchmarks for specific event types (mouse, keyboard, controller, cursor, etc.) but is missing benchmarks for the core generic_event abstraction and event_id module. Since these are foundational traits used by all event types in a game loop, performance benchmarks would help prevent regressions and document performance characteristics for maintainers.

• [ ] Create src/input/benches/generic_event.rs with benchmarks for trait object creation and downcasting
• [ ] Create src/input/benches/event_id.rs with benchmarks for event_id generation and comparison
• [ ] Benchmark event trait composition overhead compared to direct event type handling
• [ ] Document results in src/input/README.md to guide future optimization efforts

• Add missing input event benchmarks: src/input/benches/ has benches for most events but lacks comprehensive benchmarks for Touch and FocusEvent—add benches/touch.rs and benches/focus.rs to profile event creation and dispatch latency.
• Expand controller axis enum documentation: src/input/src/controller.rs defines ControllerAxis but lacks usage examples and detailed documentation of axis mapping conventions across different platforms—add code examples and platform-specific notes.
• Add integration tests for event ordering: src/input/tests/lib.rs is minimal; add tests that verify the event_loop correctly sequences mixed input types (e.g., multiple key presses followed by mouse move) to ensure event replay and ordering guarantees.

The Piston game engine repository demonstrates reasonable security posture for an open-source Rust project. No critical vulnerabilities such as hardcoded secrets, injection risks, or exposed credentials were identified. The codebase structure follows Rust best practices with proper workspace organization and modular design. Primary concerns are administrative: incomplete author metadata, lack of security policy documentation, and outdated CI infrastructure. The use of Rust as the implementation language inherently provides memory safety guarantees. Recommendations focus on improving security transparency and modernizing development infrastructure rather than addressing code-level vulnerabilities.

• Medium · Incomplete Author Email in Cargo.toml — Cargo.toml - authors field. One of the authors in Cargo.toml has an incomplete email address: 'Phlosioneer <mattmdrr2@gmail.com' is missing a closing angle bracket. This could indicate manual editing errors and potential metadata corruption. While not a direct security issue, it suggests potential for human error in manifest management. Fix: Correct the author entry to: 'Phlosioneer mattmdrr2@gmail.com' with proper closing bracket
• Low · Missing Security Policy — Repository root. No SECURITY.md or security policy file is present in the repository. This makes it difficult for security researchers to responsibly disclose vulnerabilities. Without a clear security policy, researchers may resort to public issue reporting, potentially exposing zero-day vulnerabilities. Fix: Create a SECURITY.md file with responsible disclosure guidelines, contact information, and expected response timeframes
• Low · No Dependency Lock File in Repository — Repository structure - workspace management. The repository appears to use workspace members with local path dependencies without explicit version constraints that would normally be locked. While Cargo.lock should exist locally, its absence from typical version control can lead to build reproducibility issues across different environments. Fix: Ensure Cargo.lock is committed to version control for binary crates, and document dependency management practices in CONTRIBUTING.md
• Low · Outdated CI Configuration — .travis.yml. The repository uses .travis.yml for CI/CD, which is an older CI system. Modern alternatives like GitHub Actions provide better security scanning, dependency checking, and supply chain security features. Travis CI has also had historical security incidents. Fix: Migrate to GitHub Actions or another modern CI/CD platform with built-in security scanning capabilities

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.