PlayOS

A console operating environment for handheld gaming PCs — built on Linux, presented as a dedicated gaming console.

PlayOS boots directly from UEFI into a controller-first shell. A custom compositor permanently owns the display. One hardware-accelerated game runs at a time. The player never sees a Linux desktop, terminal, or login screen.

What PlayOS Is

  • A minimal, immutable Linux system that acts as a hardware enablement layer
  • A Wayland compositor that owns DRM/KMS and enforces console display policy
  • A persistent Raylib shell that is always alive, even while a game runs
  • A stable public C ABI (libplayos) that games target instead of Linux internals
  • A thirteen-repository project with clear ownership boundaries

What PlayOS Is Not

  • A Linux distribution or desktop environment
  • A general-purpose PC OS
  • An emulation layer or compatibility shim
  • A cloud gaming platform

Documentation

Architecture and Contracts

DocumentDescription
architecture.mdSystem design, component diagrams, state machine, boot sequence
platform-api.mdPublic libplayos C ABI specification and versioning policy
runtime-ipc.mdInternal IPC protocol (launch, lifecycle, control)
wayland-protocol.mdPrivate PlayOS Wayland extensions
security-model.mdTrust boundaries, game restrictions, Secure Boot chain

Component Specifications

DocumentDescription
playos-init-spec.mdPID 1 — boot, process supervision, storage, IPC
playos-compositor-spec.mdwlroots compositor — DRM/KMS, focus, state machine
playos-shell-spec.mdRaylib shell — controller UI, game library, lifecycle
playos-overlay-spec.mdTrusted overlay — quick menu, notifications, power

Build and Development

DocumentDescription
build-guide.mdBuildroot setup, br2-external layout, make commands
kernel-config.mdKernel subsystem requirements, ROG Ally configuration
dev-environment.mdQEMU/OVMF setup, developer iteration workflow
testing.mdCI layers, physical device smoke tests

Delivery

DocumentDescription
roadmap.mdMVP criteria and sprint plan (Sprints 0–19)
post-mvp.mdPost-MVP feature roadmap
Sprint-N.mdSprint 0–19 work packages

Architecture Decision Records

ADRDecision
ADR-0001Repository structure
ADR-0002Unix socket IPC transport
ADR-0003musl libc only
ADR-0004wlroots as compositor foundation
ADR-0005RAUC for A/B updates
ADR-0006Raylib for shell and game UI
ADR-0007Direct ALSA for MVP audio
ADR-0008PCI enumeration for GPU selection

Repository Map

RepositoryRole
playos-specArchitecture, contracts, ADRs, roadmap, game developer docs
playos-platform-apiPublic libplayos C ABI
playos-runtimeInternal IPC, lifecycle transport, private Wayland protocols
playos-compositorwlroots compositor, DRM/KMS, focus, input routing
playos-shellController-first Raylib shell and PlayOS Raylib backend
playos-refdistroBuildroot integration, kernel config, image assembly, installer
playos-initPID 1 process supervisor, boot lifecycle, storage mount
playos-samplesSample games and reference applications
playos-toolsHost-side developer and OTA staging tools
playos-foundationShared foundation libraries and utilities
playos-reference-devicesReference device configurations and images
playos-cloudCloud services — cloud saves and accounts (post-MVP)
playos-marketplaceGame store and marketplace (post-MVP)

Quick Start

# Build and run in QEMU
make setup
make qemu-config
make qemu-build
make qemu-run

# Build for ROG Ally (USB image)
make ally-config
make ally-build
make ally-usb-image

See build-guide.md and dev-environment.md for full setup instructions.

Primary Device

ASUS ROG Ally — AMD Ryzen Z1 / RDNA 3 APU
First supported graphics stack: AMDGPU + Mesa RadeonSI
Intel expansion: Sprint 13