Yureka LogoDocs
GitHubyureka.dev

Architecture

OSSIM is organized into a decoupled, controller-view architecture designed for modularity and ease of extension.

1. Controller-View Pattern

OSSIM strictly separates application logic from user interface presentation:

  • The Controller (C++): UAppBase (and its children like UBlueprintApp) handles the logic, subsystem interaction, and state management.
  • The View (UMG): UUserWidget instances implement the visual layout. These widgets implement the IAppContentWidget interface to receive their controller reference automatically via InitWithApp(UAppBase* InApp).

This separation allows you to swap UI designs without touching the underlying logic, or vice-versa.

2. Session And Shell Flow

The desktop shell is managed through a staged session flow, orchestrated by UOSOrchestratorWidget and UUserSessionSubsystem.

Session States

  • EOSSessionState::Booting: Initial splash and system check.
  • EOSSessionState::SetupNeeded: No user profile found? triggers onboarding.
  • EOSSessionState::Locked: Profile exists but requires authentication to log-in.
  • EOSSessionState::LoggedIn: Active session, desktop shell is visible.
  • EOSSessionState::Idle: The desktop is active, but the user is away from the PC.

Core Shell Components

  • UOSOrchestratorWidget: The master "stage switcher" for the OS shell.
  • UBootSplashWidget: Handles the boot sequence and profile discovery.
  • UOnboardingWidget: Interactive first-time setup for new users.
  • ULoginWidget: Multi-user authentication screen.
  • UDesktopRootWidget: The parent container for the desktop, taskbar, and windows.

3. Core Subsystems

OSSIM utilizes UGameInstanceSubsystem classes for globally accessible, persistent logic.

UserSessionSubsystem

Manages authentication, user profiles, and session transitions. It is the source of truth for who is logged in and the owner of the OSSIM_UserProfile save data (UOSSIMSaveGame).

VirtualFilesystemSubsystem (VFS)

Provides a simulated Linux-like filesystem. It handles file/directory operations and per-user persistence by serializing the filesystem state into the user's profile.

WindowManagerSubsystem

Responsible for the lifecycle of application windows. It manages spawning, Z-order (stacking), focus, and window states (Minimized, Maximized).

ProcessManagerSubsystem

Tracks active application instances as simulated processes. It assigns PIDs and provides the data backend for the Task Manager App.

AppLauncherSubsystem

Orchestrates the transition from an App Class to a running Windowed App. It handles metadata reading, window mounting, and file-extension associations.

OSSIMUISubsystem

A global configuration hub for UI elements, such as registering the default UOSSIMToolTipWidget class used across the system.

SoundSubsystem

Provides OS-level audio services. It manages system sound effects (notifications, errors) and a persistent music playback engine powered by UAudioComponent. Music continues playing even after the Music Player app window is closed, since playback lives in this subsystem rather than the app widget.

4. System Boot Sequence

The OS is designed to be Auto-On. Once the UOSOrchestratorWidget is added to the viewport, it automatically drives the system through its lifecycle stages.

Sequence Details:

  1. Subsystem Init: UUserSessionSubsystem starts in EOSSessionState::Booting.
  2. Orchestrator Sync: UOSOrchestratorWidget syncs on NativeConstruct and displays the UBootSplashWidget.
  3. Boot Timer: The Splash widget runs a simulation timer (hardware delay).
  4. State Transition: Upon timer expiry, the subsystem transitions to SetupNeeded (fresh install) or Locked (existing user).
  5. UI Switch: The Orchestrator automatically flips the UI to the next stage.

The OS is auto-activated: In the OSSIM_DemoMap Outliner, locate BP_ScreenOS. Inside this actor, you'll find WBP_OS_Root (inherited from UOSOrchestratorWidget). The OS automatically initializes as soon as the widget is constructed during BeginPlay.

Press the F key to toggle the view to the PC screen or enter AFK mode. You can review this behavior in the OSSIM_DemoMap Level Blueprint.

5. Launch & Initialization Flow (Apps)

OSSIM utilizes a standardized pipeline to transition from an asset class to a functional windowed application.

  1. Request: UAppLauncherSubsystem receives a request via LaunchAppFromClass or LaunchAppForFile.
  2. Controller Init: The launcher instantiates the UAppBase controller.
  3. Window Spawn: UWindowManagerSubsystem creates the UWindowWidget frame.
  4. Content Creation: The launcher creates the content widget specified by the app controller.
  5. Interface Wiring: If the widget implements IAppContentWidget, InitWithApp(UAppBase* InApp) is called to provide the logic backend.
  6. Mounting: The initialized widget is injected into the window's body container.

6. Extensibility: Blueprint App

UBlueprintApp is a specialized implementation of UAppBase that exposes all metadata and lifecycle hooks to the Blueprint editor. This allows developers to create fully-functional OS applications without writing a single line of C++.

How To Think About The Project

  • Shell Flow: Managed by the UOSOrchestratorWidget and UUserSessionSubsystem.
  • System Logic: Lives in Subsystems (VFS, Process, Window).
  • App Controller: Inherit from UBlueprintApp or UAppBase to define behavior.
  • App View: Create UUserWidget instances that implement IAppContentWidget.
  • Persistence: Automatically handled via the FUserProfile and UVirtualFilesystemSubsystem integration into UOSSIMSaveGame.