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/Slate): Widget 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.

Content Widget Implementation Styles

Most app content widgets are native Slate hosts — they build their widget tree in RebuildWidget() rather than using the UMG Designer. This provides maximum rendering control for complex UIs.

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 (uses UWidgetSwitcher).
• UBootSplashWidget: Handles the boot sequence timer and profile discovery.
• UOnboardingWidget: Interactive first-time setup for new users.
• ULoginWidget: Multi-user authentication screen with clock display.
• UDesktopRootWidget: The parent container for the desktop, taskbar, status bar, and windows.
• UDesktopSurfaceWidget: Desktop wallpaper and right-click context menu host.
• UTaskbarWidget: Clock, app icons, Start Menu popup with animated transitions.
• UStartMenuWidget: App grid with category filtering, user avatar display.
• UStatusBarWidget: Time, date, wifi, and battery indicators.

3. Core Subsystems (11)

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).

Key APIs: Login / Logout / IsLoggedIn / GetSessionState / SetSessionState / InitializeNewProfile / AddUser / RemoveUser / ChangeUserPassword / IsAppInstalled / InstallApp / UninstallApp / SaveProfile / LoadProfile / GetHomePath / SetClipboardPaths / GetClipboardPaths / GetSystemTime.

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.

Key APIs: CreateFile / CreateDirectory / DeleteNode / MoveNode / CopyNode / ReadFile / WriteFile / ListDirectory / PathExists / GetNodeInfo / SaveToDisk / ExportVFSData / ImportVFSData.

Delegates: OnFileCreated / OnFileModified / OnFileDeleted (all dynamic/BP).

WindowManagerSubsystem

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

Key APIs: SpawnWindow / CloseWindow / MinimizeWindow / RestoreWindow / FocusWindow / MaximizeWindow / RestoreFromMaximized / SnapWindow / GetAllWindows / GetWindowById / GetFocusedWindow.

Delegates: OnWindowOpened / OnWindowClosed / OnWindowFocused / OnWindowMinimized / OnWindowStatusChanged (all dynamic/BP).

ProcessManagerSubsystem

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

Key APIs: LaunchProcess / TerminateProcess / SuspendProcess / ResumeProcess / GetRunningProcesses / GetProcessByPID / GetProcessByWindowId.

Events: OnProcessStarted / OnProcessTerminated (native C++, not Blueprint).

AppLauncherSubsystem

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

Key APIs: LaunchAppFromClass / LaunchAppFromClassWithArgs / LaunchAppForFile / MountAppIntoWindow / GetAppClassForExtension / GetAvailableApps / GetAllPossibleApps / RegisterFileAssociation / RequestFileDialog / RequestSimpleFileDialog.

Delegates: OnSimpleFileDialogResult / OnAppsChanged (dynamic/BP).

ContextMenuSubsystem

Orchestrates global right-click context menus positioned at viewport coordinates.

Key APIs: ShowContextMenu(Position, Items) / HideContextMenu / IsMenuOpen / Set/GetContextMenuClass.

Delegate: OnRequestCloseAllMenus (dynamic/BP).

SoundSubsystem

Provides OS-level audio services. It manages system sound effects and a persistent music playback engine. Music continues playing even after the Music Player app window is closed.

Key APIs: PlaySystemSound / PlayTrack / Pause / Resume / Stop / TogglePlayPause / SeekToNormalized / GetPlaybackState / GetCurrentTrack / GetPlaybackProgress / Set/GetMasterVolume / Set/GetMusicVolume / SetLooping.

Delegates: OnAudioStateChanged / OnTrackChanged (dynamic/BP).

NotificationSubsystem

Dispatches toast notifications with severity levels, auto-dismiss timers, and cap management.

Key APIs: PushNotification / Notify / NotifyInfo / NotifySuccess / NotifyWarning / NotifyError / DismissNotification / ClearNotifications / GetActiveNotifications.

Delegates: OnNotificationAdded / OnNotificationRemoved / OnNotificationsChanged (dynamic/BP).

Durations: Info=4s, Success=4s, Warning=5s, Error=6s. Max active notifications: 6.

OSSIMUISubsystem

A global configuration hub for UI elements. Inline getters/setters only.

Key APIs: Set/GetDefaultToolTipClass / Set/GetDefaultNotificationCenterClass.

EventBusSubsystem

Template-based publish-subscribe system for decoupled event communication.

Key APIs: Subscribe<T> / Unsubscribe<T> / Publish<T> / UnsubscribeAll.

OSSIMValidator (Development Only)

Auto-runs validation tests at editor startup to verify all subsystems are functioning correctly. Tests cover VFS, WindowManager, ProcessManager, UserSession, AppLauncher, and individual app metadata.

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 (2.0s 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.

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 (cascade-positioned).
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.
6. Mounting: The initialized widget is injected into the window's body container.
7. Process Registration: UProcessManagerSubsystem creates a FProcessRecord with a PID.

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++.

7. Custom Slate Widgets

OSSIM includes several high-performance custom Slate widgets:

How To Think About The Project

• Shell Flow: Managed by the UOSOrchestratorWidget and UUserSessionSubsystem.
• System Logic: Lives in Subsystems (VFS, Process, Window, Sound, Notification).
• 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.
• Install System: Apps can be installed/uninstalled per-user via UserSession and the Software Center.