# OneShot Ramen Timeline Simulator

## PURPOSE
In the episode the hosts attempt the **OneShot** challenge: "you are going to build a game with ultra fast on the new Mod Retros" — a **ramen simulator for the Mod Retro**, "obviously 8-bit", where "the goal of the game is to collect the different ingredients, put it all together, and make the best bowl of ramen possible." The recipe itself is spoken step by step: "get those eggs simmering about 11 to 12 minutes. We'll ice them after. Chop two garlic cloves. We'll warm garlic and ginger and a touch of oil. No browning", plus a rolling boil and "stir clockwise … silky bronze". This project simulates that prep timeline with **SimPy** and scores the resulting bowl with **NumPy**, so a student can tune a recipe before handing it to a player — or to an agent.

## WHY THIS MATTERS
Everything here is a scheduling problem under contention. One cook, one stove, one sink. Chopping competes with simmering, the ice bath has a deadline, and "no browning" is a hard constraint on how long garlic may stay in warm oil. That is exactly the shape of real resource scheduling, expressed with ingredients instead of jobs.

## HOW TO BUILD
1. `pip install -r requirements.txt` (SimPy, NumPy).
2. Model resources: `stove` (capacity 1) and `sink` (capacity 1).
3. Write processes: `boil_eggs` (11–12 min, then ice bath), `chop_garlic` (2 cloves), `warm_aromatics` (garlic + ginger, abort if browned), `build_broth` (rolling boil), `finish_bowl` (stir clockwise).
4. Run `env.run(until=...)`, collect a trace of `(t, actor, action)`.
5. Score with NumPy: soft-egg window, broth richness, "silky bronze" noodle target.

Key snippet — the eggs process:

```python
def boil_eggs(env, stove, sink, trace, recipe):
    with stove.request() as burner:
        yield burner.acquire()
        yield env.timeout(recipe.egg_simmer_min)      # 11-12 minutes
        trace.append((env.now, "eggs", "simmer done"))
    with sink.request() as basin:
        yield basin.acquire()
        yield env.timeout(recipe.ice_bath_min)        # "we'll ice them after"
        trace.append((env.now, "eggs", "iced"))
```

## WHEN TO USE IN PRODUCTION
Use discrete-event simulation to size shared resources: scheduling EV charging, kitchen/kitchen-lab throughput, CI runners, or any pipeline with one constrained station. Use it for design questions ("is one burner enough?") and for training agents on a cheap, deterministic environment. **Do not** use SimPy for continuous control loops or real-time control — it is a logical-time model, not a physics engine. For sub-second robotics timing, use a real simulator.

## HOW IT HELPS STUDENTS
Students learn the SimPy generator pattern, resource contention, timeouts vs. events, deadline handling ("no browning"), and turning simulated output into a scoring function — the core loop of reinforcement-learning environment design.

## STARTER CODE
See `starter/main.py`: resource setup, five recipe processes, a printed event trace, and a NumPy bowl-scoring stub.
