You’re the OS

schedule processes, swap memory pages, and keep the user calm.

▶ Run in browser

Upstream: https://github.com/plbrault/youre-the-os

Licence: this port's own code is offered under GPL-3.0-or-later, not the SimVX Examples Licence the rest of the gallery carries. See ATTRIBUTION.md for the upstream it re-implements, the terms of anything it bundles, and the credit each one requires.

Ports live in the repository only, not in the simvx-examples distribution, because each is a derivative work licensed individually against the game it re-implements. Read it with git clone https://git.simvx.com/simvx/simvx.

Tags: port tier-2

You’re the OS: SimVX port

Port of plbrault/youre-the-os, a game in which you are the operating system. Processes queue up, get hungry for CPU time, fault on memory that you left on disk, and block waiting for I/O. Nothing happens unless you make it happen, and if ten processes starve to death the user rage-quits and the machine shuts down.

Licensing note: upstream is GPL-3.0-or-later, so this port is too. See ATTRIBUTION.md and UPSTREAM_LICENSE.md.

Run

From the repository root:

uv run python examples/ports/youre_the_os/main.py            # interactive
uv run python examples/ports/youre_the_os/main.py --test     # headless capture into screenshots/
uv run simvx export web examples/ports/youre_the_os/main.py \
    -o /tmp/youre_the_os.html

How to play

The title screen lists the essentials; the bottom strip keeps a one-line reminder while you play.

• Click a process (a square in the grid) to move it onto a free CPU. Click it again to take it off. Only four processes can run at once.

• A process off the CPU slowly starves: its face sinks from a smile to a grimace while its colour runs yellow, orange, red, then darker red. At the bottom of that slide it dies and lands in the ragequit row. Ten of those and the game is over. Five seconds on a CPU resets it to a green grin.

• Click a memory page, or drag across several, to request a swap. Pages in RAM move to disk and pages on disk move back to RAM, one at a time. A running process whose page is on disk is page-faulting (it pulses blue) and makes no progress until you swap the page back in.

• Press Space, or click the I/O EVENTS box, to deliver every queued I/O event. Processes showing an hourglass are waiting on one.

• R restarts, Escape quits; the same two actions sit on the bottom strip as buttons for pointer-only and touch play.

What it shows about SimVX

• A simulation with no engine in it. nodes/state.py is plain Python: a process state machine, page allocator, swap queues, I/O queue. It imports nothing from SimVX and exposes read-only accessors (pages(), all_processes(), dead_processes()) for whatever wants to draw it.

• One node draws everything. StageNode is a single Node2D marked dynamic = True; its on_draw paints 42 process slots, ~180 page slots, four CPUs and the HUD every frame. At this element count that is far cheaper than a node per element, and it keeps the scene tree two nodes deep.

• A title screen out of the pause system. The root sets tree.paused = True and update_mode = UpdateMode.ALWAYS on itself; StageNode sets UpdateMode.PAUSABLE, so the simulation is frozen while the root keeps ticking to watch for the click that boots it. The title card and the shutdown notice are one small child node added after the stage: a node’s on_draw runs before any child that keeps a non-negative z_index, so anything that must sit on top of the playfield is easiest to add as a later sibling rather than to paint from the parent.

• Named input actions. Every mouse and key read goes through Input.is_action_pressed("primary") and friends, declared once in the root’s input_actions class attribute so the web export picks them up too.

• Signals for cross-node news. The stage emits game_over_changed once; the root notes the time and raises the shutdown notice a second later, so nothing polls the simulation for it.

• Resize-aware layout. Both nodes track tree.screen_size, so the background, the ragequit row and the controls strip follow the window (and the browser’s aspect ratio in the web export).

• Input-driven capture harness. harness.py drives the real input pipeline with InputSimulator and captures seven stages headlessly.

Files

• main.py: OsRoot scene, the title/shutdown overlay card, bottom controls strip

• nodes/state.py: the simulation (state machine, pages, swaps, I/O, scoring)

• nodes/stage.py: StageNode, all layout, drawing and input hit-testing

• nodes/theme.py: colour palette and the ASCII faces standing in for upstream’s emoji

• harness.py: scripted seven-stage screenshot capture

• screenshots/: output of --test

Deviations from upstream

• Single difficulty (upstream’s Normal): four CPUs, 42 process slots, 128 RAM page slots and 48 on disk.

• No image assets at all. Upstream’s OpenMoji process faces become ASCII faces and the hourglass is drawn from rectangles, so the web export carries no texture payload.

• No sound, no high-score table, no in-game options screen.

Source files

File	Summary	Lines
main.py	You’re the OS: schedule processes, swap memory pages, and keep the user calm.	314
harness.py	Scripted-input harness: drives the port headlessly and captures seven stages.	133
nodes/__init__.py	Port of You’re the OS: node modules.	1
nodes/stage.py	StageNode: the playfield.	425
nodes/state.py	Pure-Python game-state model.	754
nodes/theme.py	Colour palette and process-face glyph map.	80

Source

"""You're the OS: schedule processes, swap memory pages, and keep the user calm.

# /// simvx
# tags = ["port", "tier-2"]
# upstream = "https://github.com/plbrault/youre-the-os"
# web = { width = 1280, height = 720, responsive = true }
# ///

A port of Pier-Luc Brault's "You're the OS!". You are the operating system: put
processes on one of four CPUs before they starve, swap their memory pages
between RAM and disk to clear page faults, and deliver queued I/O events. Ten
starved processes and the user rage-quits: shutdown.

The simulation is plain Python with no engine imports (``nodes/state.py``), and
one dynamic ``Node2D`` draws all 42 process slots and ~180 page slots in
``on_draw``. Input is polled through named input actions, the title screen is
just ``tree.paused`` plus an ``UpdateMode``, and game-over reaches the root as a
Signal.

Controls: click a process to move it on or off a CPU, click or drag across pages
to request and cancel swaps, Space or a click on the I/O box delivers events, R
restarts, Escape quits.

Run:
    uv run python examples/ports/youre_the_os/main.py            # interactive
    uv run python examples/ports/youre_the_os/main.py --test     # headless capture
"""

from __future__ import annotations

import sys
from pathlib import Path

_PORT_DIR = Path(__file__).parent
if str(_PORT_DIR) not in sys.path:
    sys.path.insert(0, str(_PORT_DIR))

from nodes import theme  # noqa: E402
from nodes.stage import DESIGN_HEIGHT, DESIGN_WIDTH, StageNode  # noqa: E402

from simvx.core import Node2D, Signal, UpdateMode  # noqa: E402
from simvx.core.input.enums import Key, MouseButton  # noqa: E402
from simvx.core.input.state import Input  # noqa: E402
from simvx.core.math.types import Vec2  # noqa: E402
from simvx.core.text import measure_text_width  # noqa: E402
from simvx.graphics import App  # noqa: E402

# Bottom controls strip: port-UX baseline
STRIP_HEIGHT = 70
BUTTON_W = 130
BUTTON_H = 44
BUTTON_GAP = 18

HINT = "Click a process to schedule it - Space delivers I/O"
HINT_SCALE = 0.75
HINT_MARGIN = 16

SHUTDOWN_DELAY_S = 1.0  # let the last ragequit land before the overlay covers it

PANEL_PAD = 36
PANEL_LINE_GAP = 22
TITLE_LINES = [
    ("YOU'RE THE OS", 3.0, (0.6, 0.85, 1.0, 1.0)),
    ("Click a process to put it on a CPU. Click it again to take it off.", 1.0, theme.WHITE),
    ("Click or drag across memory pages to swap them between RAM and disk.", 1.0, theme.WHITE),
    ("Press Space (or click the I/O box) to deliver waiting I/O events.", 1.0, theme.WHITE),
    ("Let ten processes starve and the user rage-quits.", 1.0, (0.85, 0.75, 0.55, 1.0)),
    ("Click anywhere or press Space to boot", 1.3, (0.6, 0.95, 0.8, 1.0)),
]


class _Button:
    def __init__(self, label: str, action: str) -> None:
        self.label = label
        self.action = action
        self.x = 0.0
        self.y = 0.0
        self.w = BUTTON_W
        self.h = BUTTON_H
        self.hovered = False
        self.pressed = False

    def contains(self, mp: Vec2) -> bool:
        return (
            self.x - self.w * 0.5 <= mp.x <= self.x + self.w * 0.5
            and self.y - self.h * 0.5 <= mp.y <= self.y + self.h * 0.5
        )


class _OverlayCard(Node2D):
    """Dimmed panel of centred text: the title card and the shutdown notice.

    Added to the root *after* the stage so it paints on top of it. A node's own
    on_draw runs before any child that keeps a non-negative ``z_index``, so the
    root itself can only paint what belongs underneath the playfield.
    """

    dynamic = True

    def __init__(self, **kwargs) -> None:
        super().__init__(**kwargs)
        self.lines: list[tuple[str, float, tuple[float, float, float, float]]] = []

    def show(self, lines) -> None:
        self.lines = list(lines)

    def hide(self) -> None:
        self.lines = []

    def on_draw(self, renderer) -> None:
        if not self.lines:
            return
        vw, vh = self.tree.screen_size
        renderer.draw_rect((0, 0), (vw, vh), colour=(0.0, 0.0, 0.0, 0.86), filled=True)

        # Panel sized to the text it holds, so the copy stays legible over the
        # playfield at any viewport size.
        line_heights = [26 * scale + PANEL_LINE_GAP for _, scale, _ in self.lines]
        panel_w = max(measure_text_width(text, scale) for text, scale, _ in self.lines) + 2 * PANEL_PAD
        panel_h = sum(line_heights) - PANEL_LINE_GAP + 2 * PANEL_PAD
        top = (vh - panel_h) * 0.5 + PANEL_PAD
        panel = ((vw - panel_w) * 0.5, top - PANEL_PAD)
        renderer.draw_rect(panel, (panel_w, panel_h), colour=(0.04, 0.05, 0.08, 0.98), filled=True)
        renderer.draw_rect(panel, (panel_w, panel_h), colour=(0.30, 0.42, 0.58, 1.0), filled=False)

        y = top
        for (text, scale, colour), line_h in zip(self.lines, line_heights, strict=True):
            _draw_centred_text(renderer, text, vw * 0.5, y, scale=scale, colour=colour)
            y += line_h


class OsRoot(Node2D):
    """Root scene: background, the Stage, the overlay card, and the bottom controls strip."""

    input_actions = {
        "primary": [MouseButton.LEFT],
        "secondary": [MouseButton.RIGHT],
        "deliver_io": [Key.SPACE],
        "restart": [Key.R],
        "quit": [Key.ESCAPE],
    }

    button_pressed = Signal()

    def on_ready(self) -> None:
        # The title card sits on a paused tree, so the root has to keep ticking
        # to notice the click that boots the machine. StageNode opts back into
        # PAUSABLE so only this node stays live behind the card.
        self.update_mode = UpdateMode.ALWAYS

        self.viewport_size = Vec2(DESIGN_WIDTH, DESIGN_HEIGHT)
        self._sync_viewport()

        self.stage = StageNode()
        self.add_child(self.stage)
        self.stage.game_over_changed.connect(self._on_game_over)
        self._shutdown_at: float | None = None

        # Boot into the title card: the playfield is laid out behind it but its
        # simulation stays frozen until the player starts the machine.
        self.started = False
        self.overlay = self.add_child(_OverlayCard(name="Overlay"))
        self.overlay.show(TITLE_LINES)
        self.tree.paused = True

        # Bottom controls
        self.buttons: list[_Button] = [
            _Button("Restart", "restart"),
            _Button("Quit", "quit"),
        ]
        self._press_target: _Button | None = None
        self.button_pressed.connect(self._on_button)

        # The root's on_draw renders button hover and press state, which lives in
        # plain attributes mutated from on_update rather than in Properties, so
        # none of those writes dirty this node and its retained draws would go
        # stale. Mark the root dynamic: its small on_draw (background, strip and
        # two buttons) re-captures every frame while the heavy stage stays
        # retained.
        self.dynamic = True

    # ------------------------------------------------------------------ tick
    def on_update(self, dt: float) -> None:
        self._sync_viewport()

        if Input.is_action_just_pressed("quit"):
            self._on_button("quit")
            return

        if not self.started:
            if Input.is_action_just_pressed("primary") or Input.is_action_just_pressed("deliver_io"):
                self._start()
            return

        # Layout buttons across the bottom strip
        vw, vh = self.viewport_size.x, self.viewport_size.y
        n = len(self.buttons)
        total_w = n * BUTTON_W + (n - 1) * BUTTON_GAP
        x0 = (vw - total_w) * 0.5 + BUTTON_W * 0.5
        y = vh - STRIP_HEIGHT * 0.5
        for i, b in enumerate(self.buttons):
            b.x = x0 + i * (BUTTON_W + BUTTON_GAP)
            b.y = y

        mp = Input.mouse_position
        for b in self.buttons:
            b.hovered = b.contains(mp)
            b.pressed = b.hovered and Input.is_action_pressed("primary") and self._press_target is b
        if Input.is_action_just_pressed("primary"):
            for b in self.buttons:
                if b.contains(mp):
                    self._press_target = b
                    break
        if Input.is_action_just_released("primary"):
            if self._press_target and self._press_target.contains(mp):
                self.button_pressed(self._press_target.action)
            self._press_target = None

        if Input.is_action_just_pressed("restart"):
            self._on_button("restart")

        # Let the last rage-quit land on screen before the notice covers it.
        if self._shutdown_at is not None and self.tree.now - self._shutdown_at > SHUTDOWN_DELAY_S:
            self._show_shutdown()

    def _sync_viewport(self) -> None:
        w, h = self.tree.screen_size
        if (w, h) != (self.viewport_size.x, self.viewport_size.y):
            self.viewport_size = Vec2(w, h)

    # ------------------------------------------------------------------ draw
    def on_draw(self, renderer) -> None:
        vw, vh = self.viewport_size.x, self.viewport_size.y

        # Dark background
        renderer.draw_rect((0, 0), (vw, vh), colour=theme.DARK_BG, filled=True)

        if not self.started:
            # The title card child paints over the playfield; the controls strip
            # would only show through it.
            return

        # Bottom strip background
        strip_y = vh - STRIP_HEIGHT
        renderer.draw_rect((0, strip_y), (vw, STRIP_HEIGHT), colour=(0.78, 0.80, 0.83, 1.0), filled=True)
        renderer.draw_rect((0, strip_y), (vw, 1), colour=(0.55, 0.58, 0.62, 1.0), filled=True)
        # Hint sits left of the centred buttons, and yields to them on a window
        # too narrow to hold both.
        hint_end = HINT_MARGIN + measure_text_width(HINT, HINT_SCALE) + HINT_MARGIN
        if hint_end < min(b.x - b.w * 0.5 for b in self.buttons):
            renderer.draw_text(HINT, (HINT_MARGIN, strip_y + 28), scale=HINT_SCALE, colour=(0.06, 0.08, 0.12, 1.0))
        for b in self.buttons:
            base = (0.92, 0.94, 0.96, 1.0)
            if b.pressed:
                base = (0.55, 0.65, 0.85, 1.0)
            elif b.hovered:
                base = (0.86, 0.92, 0.99, 1.0)
            renderer.draw_rect((b.x - b.w * 0.5, b.y - b.h * 0.5), (b.w, b.h), colour=base, filled=True)
            renderer.draw_rect(
                (b.x - b.w * 0.5, b.y - b.h * 0.5),
                (b.w, b.h),
                colour=(0.3, 0.35, 0.4, 1.0),
                filled=False,
            )
            _draw_centred_text(renderer, b.label, b.x, b.y - 8, scale=0.85, colour=(0.05, 0.07, 0.11, 1.0))

    # ---------------------------------------------------------------- glue
    def _start(self) -> None:
        self.started = True
        self.overlay.hide()
        self.tree.paused = False

    def _on_game_over(self) -> None:
        """The stage announced a shutdown: note when, so the notice can follow it."""
        self._shutdown_at = self.tree.now

    def _show_shutdown(self) -> None:
        stats = self.stage.state.stats
        finished = f"{stats.score} process{'' if stats.score == 1 else 'es'} finished happily"
        self.overlay.show(
            [
                ("SHUTDOWN", 3.0, (1.0, 0.4, 0.4, 1.0)),
                (finished, 1.2, theme.WHITE),
                (f"{stats.ragequits} rage-quits", 1.2, (0.95, 0.7, 0.55, 1.0)),
                ("Press R to boot again", 1.0, (0.6, 0.95, 0.8, 1.0)),
            ]
        )

    def _on_button(self, action: str) -> None:
        if action == "restart":
            self._shutdown_at = None
            self.overlay.hide()
            self.stage.restart()
        elif action == "quit":
            self.app.quit()


def _draw_centred_text(renderer, text: str, cx: float, y: float, *, scale: float, colour) -> None:
    """Draw *text* horizontally centred on *cx*, measured from the font's own advances."""
    renderer.draw_text(text, (cx - measure_text_width(text, scale) * 0.5, y), scale=scale, colour=colour)


def main() -> None:
    if "--test" in sys.argv:
        from harness import run_harness

        run_harness()
        return
    app = App(width=DESIGN_WIDTH, height=DESIGN_HEIGHT, title="You're the OS (SimVX)")
    app.run(OsRoot())


if __name__ == "__main__":
    main()