Hycel

A small, deterministic 2D game engine designed to be built and tested by people and AI agents.

Hycel is pre-alpha: its workspace includes a deterministic simulation kernel, early native window/sprite/input paths, project tools, and a small windowed two-room platformer vertical slice. The sample is an integration proof, not a release-quality game, and no gameplay API or project format is stable. The first release is intentionally a narrow, reliable 2D engine—not a broad 3D editor.

Why Hycel

Game projects should be inspectable and testable without clicking through an editor. Hycel aims to make the same project usable by a person, a script, CI, or an AI agent:

• readable, versionable project and scene files;
• deterministic headless simulation and replayable input;
• stable CLI commands with machine-readable output;
• structured diagnostics that explain what failed and where;
• visual runtime/editor workflows added without making them the only interface.

Current state

• hycel-core: fixed-rate integer simulation clock and deterministic world/schedule/replay primitives; no platform APIs.
• hycel-project: bounded TOML/JSON manifest and scene/resource parsing with strict fields, path checks, and stable diagnostics; project formats are still experimental.
• hycel-assets: bounded source hashing, versioned import fingerprints/records, deterministic cache/reimport decisions, and scene/resource dependency reports including animation-frame texture edges; format decoders and importer execution are not implemented.
• hycel-animation: strict project-authored clip resources, contiguous tick-driven playback, deterministic loop/completion events, and scene transitions applied at explicit tick boundaries; see docs/scene-format.md.
• hycel-audio: best-effort Kira-backed one-shot effects and looping music with bounded encoded inputs, silent fallback, and bounded asynchronous diagnostics; see ADR 0004.
• hycel-save: strict, bounded per-user progress saves with atomic replacement, one backup, and explicit recovery; see ADR 0005.
• hycel-cli: hycel new, check, and read-only inspect foundations with versioned JSON envelopes and stable exit codes.
• hycel-demo: a headless movement prototype and a windowed platformer vertical slice composing tick-indexed input, Rapier physics, authored animation/scenes, best-effort audio, and local progress saves. The release-mode performance harness records repeatable CPU workloads. The vertical slice is documented in docs/platformer-vertical-slice.md.
• hycel-platform/hycel-render: provisional native window and early 2D sprite backend with bounded RGBA uploads, camera/layer/tint support, and a bitmap debug-text overlay. Image decoding remains outside the renderer; see docs/rendering.md.
• hycel-input: strict versioned named keyboard/mouse actions, tick-indexed input frames, and replayable action edges; see docs/input.md.
• hycel-physics: early Rapier2D adapter with fixed-tick box bodies, bounded fixed-point conversion, and sorted contact transitions; see docs/adr/0003-physics-backend.md.
• CI: format, lint, test, and build across macOS, Linux, and Windows runners.
• Project and scene schema proposals: docs/project-format.md and docs/scene-format.md, with parser implementation in hycel-project; asset identity and import contracts are in docs/asset-pipeline.md.
• Design and release requirements: docs/, including the gameplay capability profile, physics backend decision, progress save decision, early 2D rendering guide, and input binding guide.
• Product contract: docs/product-scope.md.
• Planned OS, CPU, compiler, and GPU-backend matrix: docs/support-matrix.md.
• Engineering, data-integrity, privacy, and dependency rules: docs/engineering-contracts.md.
• Phased path to stable 1.0: docs/roadmap.md; baseline methodology and limits are in docs/performance-baselines.md.

Run the headless demo, project CLI, and windowed vertical slice (from the repository root):

cargo run -p hycel-demo
cargo run -p hycel-demo --example performance_baseline --release
cargo run -p hycel-demo --example playable_platformer
cargo run -p hycel-cli -- --help
cargo run -p hycel-cli -- new ./MyGame --name "My Game"
cargo run -p hycel-cli -- check ./MyGame --json
cargo test --workspace

CLI command and JSON contracts are documented in docs/cli.md.

The windowed sample opens on a title overlay. Press Space to start; hold A/D or the arrow keys to move, tap Space to jump, and press R to respawn/replay. Check examples/platformer-game with hycel-cli before editing its strict project data.

Status and compatibility

This is pre-alpha and does not yet promise a stable project format, gameplay API, or save compatibility. Target matrix for the first release: macOS, Linux, and Windows on x86-64 and ARM64. Platform support will be declared per release only after native CI and game smoke tests pass. The project is licensed under Apache-2.0; see LICENSE.

Contributing

See CONTRIBUTING.md, MAINTAINERS.md, the Code of Conduct, architecture, engineering contracts, and release 0.1. No engine API is considered stable until a later release explicitly says so.