Documentation

Back to home

Getting started

  1. Download the DMG and drag OS Engine into Applications.
  2. Open the app from Applications. The main window will appear.
  3. Use the status bar icon (top right) to Show/Hide the window anytime.

Enable video wallpapers

On macOS, ensure Desktop & Dock → Desktop & Stage Manager → Show Items is set to On Desktop. This must be ON for video wallpapers to appear.

macOS Desktop & Dock setting — Show Items: On Desktop

Using wallpapers

  • Add video or web wallpapers from the Library.
  • Assign different wallpapers to each display.
  • Use Automation to pause on battery, fullscreen, or per‑app focus.

Create interactive HTML overlays

Overlays are standard HTML/CSS/JS snippets rendered over your video or image wallpaper. You can add them in the Editor via Add HTML, or generate with the built‑in Ollama integration.

  1. Open the Editor (right‑click a wallpaper → Edit).
  2. Click Add HTML and paste your snippet.
  3. Position/resize elements in the canvas. Save a version, or upload to the marketplace.

Overlay guidelines

  • Use a single root container sized to the canvas: <div style="position:absolute;left:0;top:0;width:100vw;height:100vh">…</div>.
  • For each widget, absolutely position inside the root (the editor lets you drag/resize).
  • To make an overlay interactive (click/hover/keyboard), include data-interactive on any element or add the HTML comment <!-- interactive --> anywhere in your snippet.
  • Prefer pointer-events: none for purely visual overlays. When the engine detects your interactive marker, it automatically enables pointer events on your overlay so clicks/hover work.
  • Keep backgrounds transparent; avoid forcing body to opaque colors.

Click/hover examples

<!-- interactive -->
<!-- Pulsing circle that reacts to hover -->
<div data-interactive style="position:absolute;left:40px;top:40px;width:140px;height:140px;border-radius:50%;background:#35a2ff66;transition:transform .2s">
  <script>
    const el = document.currentScript.parentElement;
    el.addEventListener('mouseenter', () => el.style.transform = 'scale(1.15)');
    el.addEventListener('mouseleave', () => el.style.transform = 'scale(1)');
  </script>
</div>
<!-- interactive -->
<!-- Clock widget (updates every second) -->
<div id="clock" data-interactive style="position:absolute;right:40px;top:40px;padding:10px 14px;border-radius:8px;background:#00000055;color:#fff;font:14px system-ui">
  00:00
  <script>
    const box = document.getElementById('clock');
    setInterval(() => {
      const d = new Date();
      box.textContent = d.toLocaleTimeString();
    }, 1000);
  </script>
</div>

Three.js overlays

Enable the Three.js toggle in Preferences, then use the Editor’s “Three.js Scene” button to insert a template. You can tweak JSON parameters (geometry, color, rotation) in the Inspector panel. Note: for interactive Three scenes, also add data-interactive to your root element.

Performance tips

  • Prefer CSS transforms/opacity for animations; avoid heavy reflows.
  • Throttle timers and avoid unnecessary network requests in overlays.
  • Keep images small; host static assets on a CDN where possible.

Troubleshooting

  • Window not visible: From the menu bar choose File → New → New Window, or click the status bar icon and choose “Show Window”.
  • No wallpaper showing: Make sure a wallpaper is running and you are not in fullscreen or battery-saver pause.