# anne_terminal_input

`anne_terminal_input` is a Rust library for capturing and processing terminal key events in raw mode. It leverages `crossterm` for cross-platform terminal I/O, `uuidmap::Table` for in-memory event queues, and integrates seamlessly with the `world_dispatcher` ECS-style dispatcher.

## Features

- **Raw Mode Control**  
  Re-exported functions:
  - `enable_raw_mode()` — call at application start-up
  - `disable_raw_mode()` — call on shutdown
- **Event Representation**  
  ```rust
  pub struct KeyInputEvent {
      pub code: KeyCode,     // the key code pressed
      pub order: u64,        // frame-specific order counter
  }
  ```
- **Event Handling**  
  - `handle_event(table, counter, event)` captures a single key event into a `Table<KeyInputEvent>` and updates the order
- **Polling System**  
  - `input_system(table)` clears previous frame events and polls for pending key events, inserting them into the table
- **ECS Integration**  
  Systems can be converted via `.add(your_fn)` into a `world_dispatcher::Dispatcher` and run as part of an ECS pipeline
- **Storage**  
  Uses `uuidmap::Table` (a dense, `u128`-keyed storage).

## Getting Started

1. **Add to your `Cargo.toml`**
   ```toml
   [dependencies]
   world_dispatcher = "*"
   anne_terminal_input = "*"
   uuidmap = "*"
   ```

2. **Enable raw mode** (before your main loop)
   ```rust
   use anne_terminal_input::enable_raw_mode;
   enable_raw_mode()?;
   ```

3. **Capture key events**
   ```rust
   use anne_terminal_input::{handle_event, input_system, KeyInputEvent};
   use uuidmap::Table;

   let mut table: Table<KeyInputEvent> = Default::default();
   input_system(&mut table)?; // polls and captures any pending key event

   for evt in table.values() {
       println!("Event #{}: {:?}", evt.order, evt.code);
   }
   ```

4. **Disable raw mode** (on exit)
   ```rust
   use anne_terminal_input::disable_raw_mode;
   disable_raw_mode()?;
   ```

## ECS Example with `world_dispatcher`

```rust
use anne_terminal_input::{input_system, enable_raw_mode, disable_raw_mode, KeyInputEvent};
use uuidmap::Table;
use world_dispatcher::{DispatcherBuilder, World, SystemResult};
use crossterm::event::{Event, KeyEvent, KeyCode, KeyModifiers};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Enter raw mode (before your game loop)
    enable_raw_mode()?;

    // Create World and initialize the table resource
    let mut world = World::default();
    world.get_mut_or_default::<Table<KeyInputEvent>>();

    // Build dispatcher with the polling system
    let mut dispatcher = DispatcherBuilder::default()
        .add(input_system)
        .build(&mut world);

    // Run one ECS frame: polls and stores events
    dispatcher.run_seq(&world)?;

    // Retrieve and process captured key events
    let table = world.get::<Table<KeyInputEvent>>().unwrap();
    for evt in table.values() {
        println!("Captured event: {:?}", evt);
    }

    // Exit raw mode when done
    disable_raw_mode()?;
    Ok(())
}
```

## AI Use
This code was mostly generated using AI along human guidance and multiple rounds of manual code review.