🕰️ Hyperclock

A high-performance, event-driven, phased time engine for Rust, designed for simulations, game development, and complex, time-sensitive applications.

What is Hyperclock?

Hyperclock is a library for building complex, time-sensitive, and event-driven applications in Rust. It provides a powerful "phasetime" engine that acts as the central nervous system for your project, allowing you to schedule logic, react to events, and manage complex automations with a clean, decoupled architecture.

It's designed for applications that need to manage a lot of concurrent logic that happens over time, such as:

Game engines (especially for managing game loops and AI ticks)
Simulations and modeling systems
Interactive media and robotics
Complex industrial automation and process control

✨ Core Features

⏱️ High-Resolution Clock: A configurable master clock that can tick hundreds of times per second, suitable for real-time applications (Low, Medium, High, Ultra).
🔄 Configurable Phase Cycle: Define a custom sequence of logical phases (e.g., "input", "logic", "render") that execute on every single tick, giving your application a predictable heartbeat.
📣 Powerful Event System: A fully asynchronous, multi-channel event bus. Your application's components are completely decoupled and communicate by subscribing to and broadcasting strongly-typed events.
🗓️ Rich Task Scheduling:
- Intervals: Run tasks at a regular interval (e.g., every 5 seconds).
- Conditionals: Trigger tasks only when a specific condition in your application's state is met.
- Lifecycle Loops: Define complex, multi-step automations that execute a sequence of actions over time.
🦀 Safe Concurrency: Built from the ground up with tokio and thread-safe primitives (Arc, RwLock, SlotMap) to ensure your application is robust and free from data races.
🐚 Interactive Shell: Comes with hypershell, a fully interactive command-line application for live testing and interaction with a running Hyperclock engine.

🏁 Getting Started: The Interactive Shell

The fastest way to experience Hyperclock is to run the hypershell.

Prerequisites

Rust and Cargo (2021 edition or later)
Git

Running the Shell

Clone the repository:

git clone https://github.com/your-username/hyperclock-project.git
cd hyperclock-project

Run hypershell: The -p flag tells Cargo to run the rdx-hypershell package from within the workspace.
```
cargo run -p rdx-hypershell
```

Interactive Session Example

Once running, you can interact with the live engine.

# The shell starts up with the banner and prompt
>> 

# Add a task that will fire every 3 seconds
>> add interval 3
--> Added interval listener with handle: #0

<-- [SYSTEM EVENT] ListenerAdded { id: ListenerId(0v1) }
>> 

# See the list of active listeners
>> list
Active Listeners:
  Handle #0: ListenerId(0v1)
>> 

# After 3 seconds, the background engine fires the task!
<-- [INTERVAL TASK] A 3-second interval fired!

# Remove the listener using its handle
>> remove interval 0
--> Listener successfully removed.

<-- [SYSTEM EVENT] ListenerRemoved { id: ListenerId(0v1) }
>>

# The task will no longer fire. Now exit the shell.
>> exit
Exiting hypershell...

# The engine shuts down gracefully
INFO [Hyper Engine] has shut down.

📚 Usage as a Library

To use Hyperclock in your own project, add rdx-hyperclock as a dependency.

Basic Engine Setup

Here's how to initialize and run the engine in your own main.rs.

use rdx_hyperclock::prelude::*;
use std::time::Duration;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Create a configuration for the engine.
    let config = HyperclockConfig {
        resolution: ClockResolution::High, // 60 ticks per second
        ..Default::default()
    };

    // 2. Create the engine instance.
    let engine = HyperclockEngine::new(config);

    // 3. Register your application's logic.
    engine.on_interval(
        PhaseId(0),
        Duration::from_secs(1),
        || println!("One second has passed!")
    ).await;

    // 4. Run the engine. This is a blocking call.
    engine.run().await?;

    Ok(())
}

🔧 Configuration

The engine's behavior can be configured via a TOML file. You would create a config.toml file and load it using the config crate in your application.

Example config.toml:

# Set the master clock to run at 120 ticks per second.
resolution = "ultra"

# Define a 3-phase cycle for our game loop.
[[phases]]
id = 0
label = "input_processing"

[[phases]]
id = 1
label = "game_logic_and_physics"

[[phases]]
id = 2
label = "render_prep"

🛣️ The Road Ahead

Hyperclock is under active development. Key features planned for the future include:

Dynamic Engine Control: Refactoring the engine to use a Command Pattern for extreme robustness and thread safety.
Snapshot & Rehydration: The ability to save the engine's entire state to a file and restore it later.
Crontab-style Task Loading: Defining tasks and listeners in a data file that can be hot-reloaded while the engine is running.
Web Dashboard: A simple web interface for monitoring and controlling a running Hyperclock instance.

🗃️ Rustadex Codex

Hyperclock & Hypershell are part of the Rustadex (RDX) Codex. Library of Rust-based tools and parts for general junkyard engineering. Build a rocket.

🤝 Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

📜 License

This project is dual-licensed under the terms of both the MIT license and the Apache License, Version 2.0.

rdx-hyperclock 0.3.1