OOPS Ecosystem User Guide

Welcome to the OOPS (Orbistoun, obSCEne, Prosperous, SELFish) user guide.

This guide is designed for homebrew developers, operators, hardware testers, and curious users who want to build, package, deploy, or emulate console applications using 100% clean-room, first-party tools.

If you are an AI coding agent or an emulator/compiler architect looking for formal specifications, ABI layouts, or decision records, consult the Technical Reference & THE LOOP instead.

Table of Contents

  1. Prerequisites & Environment Setup
  2. Building & Installing the First-Party Tools
  3. End-to-End Workflows
  4. Component User Guides
  5. Troubleshooting & FAQ

1. Prerequisites & Environment Setup

OOPS uses a dual-environment toolchain:

Required Software:

  1. Rust Toolchain: Rust 1.80+ (rustup default stable).
  2. Container or WSL for Target Cross-Compilation:
    • Windows: Use WSL2 (with Ubuntu / Debian) or Docker Desktop (silkeh/clang:18).
    • Linux: Clang 18+ and lld installed natively.

2. Building & Installing the First-Party Tools

To build the primary host command-line tools into your environment:

# In PowerShell (Windows) or bash (Linux)
git clone https://github.com/project-oops/OOPS.git
cd OOPS

# Build the packager (selfish)
cargo build --release -p selfish-cli
# Build the target bridge (pros)
cargo build --release -p pros-cli
# Build the emulator (orbistoun)
cargo build --release -p orbistoun-cli

Binaries will land in target/release/ (selfish.exe, pros.exe, orbistoun.exe). Add this directory to your PATH or invoke them directly.

3. End-to-End Workflows

  [C Source Code]
        │ (make in WSL / Docker)
        ▼
   [app.elf]
        │
        ├── (selfish --format title) ──► [Title Directory: GLCB00001/]
        │                                      │
        │                                      ├── (pros restore / launch) ──► Physical PS5
        │                                      │
        │                                      └── (orbistoun run) ──────────► Orbistoun Emulator
        ▼
   [eboot.bin]

Workflow A: Build and Package Homebrew

  1. Compile the App Payload: In your WSL terminal or Linux shell, navigate to an app in oops-apps:

    cd oops-apps/src/gl-cube
make title

    This automatically:

    • Compiles freestanding C source into gl-cube.elf.
    • Compiles the companion libc.prx module.
    • Calls selfish --format title to layout build/title/GLCB00001/ with generated param.json, icon0.png, keystone, nptitle.dat, and pfs-version.dat.

  2. Verify Title Directory: Inspect the contents:

    ls build/title/GLCB00001
# Output: eboot.bin, sce_module/, sce_sys/

Workflow B: Deploy & Manage on Real Hardware

  1. Register Your Target Console:

    pros.exe register 192.168.1.211 --name ps5-testbed

  2. Verify Console Health:

    pros.exe check

    Expectation: All 5 active ports should respond (elfldr:9021, ftpsrv:2121, klogsrv:3232, shsrv:2323, pldmgr:8084).

  3. Stage the Title:

    pros.exe restore build/title/GLCB00001 /data/homebrew/GLCB00001

  4. Launch and Stream Telemetry:

    # In terminal 1: Stream live system logs
pros.exe logs

# In terminal 2: Launch the title
pros.exe launch GLCB00001

Workflow C: Run & Test in the Orbistoun Emulator

  1. Run Title Directory:

    orbistoun.exe run build/title/GLCB00001

  2. Inspect Call Report & Compare Traces:

    # View calls made by the guest during execution
orbistoun.exe report

# Compare against the previous execution trace
orbistoun.exe verify

4. Paths and Portable Mode Across OOPS

All host tools in the collection (pros, orbistoun, selfish, obscene-tool) share a unified platform storage layout resolved at runtime by oops-paths:

Default Storage Layout

All tools share this directory:

%APPDATA%\OOPS\
├── targets.txt      <- Registered consoles (shared between pros, orbistoun, and obscene)
├── titles/          <- Staged titles and guest filesystems (shared between pros and orbistoun)
├── saves/           <- Mounted save files
└── reports/         <- Hardware conformance reports and telemetry

Portable Mode

Drop a .portable directory (or sentinel file) next to your OOPS executables, or set OOPS_PORTABLE=1:

<wherever you put your tools>/
    pros.exe
    orbistoun.exe
    selfish.exe
    .portable        <- Sentinel directory or file
    targets.txt      <- Written right beside the binaries
    titles/
    saves/

In portable mode:

5. Modular Component User Guides

Following the in-house documentation standard, each project maintains dedicated, per-screen modular feature documents with screenshot placeholders and CLI/GUI side-by-side parity:

6. Troubleshooting & FAQ

Q: Why does pros check report target timeout?

Q: Can I run commercial retail games in Orbistoun right now?

Q: Why does pros restore fail with directory errors?