Building from source

You only need this guide to change the main application. To build an external plugin, use writing plugins; plugin projects do not need a MAUI application build or a sibling SDK checkout.

Windows prerequisites

  • A Git checkout of MultiShock.
  • The .NET 10 SDK, including a version accepted by the checkout's global.json.
  • The MAUI workload and Windows SDK required by MultiShock.csproj. Use Visual Studio's MAUI development workload or restore the project's workloads with the .NET CLI.
  • Node.js and the pnpm version selected by package.json for Tailwind builds.

The current Windows target is net10.0-windows10.0.22621.0. Its minimum runtime OS version is Windows 10 build 17763; the target SDK number is a build-time requirement. global.json currently selects SDK 10.0.100 with latestPatch roll-forward, so an installed SDK from a different feature band alone may not satisfy it. Check the files in your checkout before substituting newer versions.

Build and run

Run these commands from the application repository directory containing MultiShock.csproj, global.json, and package.json:

dotnet --version
dotnet workload restore MultiShock.csproj
pnpm install --frozen-lockfile
pnpm run rebuild:tailwind
dotnet build MultiShock.csproj -f net10.0-windows10.0.22621.0

Close any installed copy before launching the development build:

dotnet watch --project MultiShock.csproj run -f net10.0-windows10.0.22621.0 -- --enable-dev-tools

Development builds share the normal per-user configuration and flows. Back them up before development. Stop existing automation and use a test setup with shocks disabled before running changed code. Unpackaged builds skip the installed app's automatic updater.

For Razor or theme changes, watch core CSS in a second terminal:

pnpm run watch:css

Run pnpm run rebuild:tailwind when changes also need to reach the shared plugin stylesheet. The application uses Tailwind 3; the separate website has its own package manifest and toolchain.

Find the relevant code

Directory or fileResponsibility
Components/Pages/Home, settings, devices, diagnostics, and plugin management UI
Components/FlowEditor/Canvas, node palette, property panel, and flow library UI
Components/Layout/Sidebar, app navigation, and shortcuts
Core/MAUI composition and application lifecycle
Platforms/Native startup and platform-specific integration
Plugins/PluginHost.csDesktop implementation of SDK host services
MultiShock.Core/Configuration/Settings models, persistence, paths, and migrations
MultiShock.Core/Flow/Engine/Flow definitions, runtime, registry, validation, and storage
MultiShock.Core/Flow/Editing/Editor state, history, and canvas event routing
MultiShock.Core/Flow/Nodes/Built-in nodes
MultiShock.Core/Plugins/Discovery, manifests, load contexts, catalog, and reload
MultiShock.Core/Services/Device actions, queues, transports, and startup orchestration
Tests/Portable core regression tests
wwwroot/, tailwind.tokens.jsWeb assets and application design tokens

MultiShock.Core.csproj references the published PiShock.MultiShock.PluginSdk package. Its package version is the host's SDK contract. Installing a different NuGet version in a plugin does not upgrade the SDK inside the application.

Checks

The core tests do not require a MAUI desktop build:

dotnet test Tests/MultiShock.Tests.csproj

Run a desktop build for UI or platform changes and test the affected behavior in the app. Passing portable tests does not verify sign-in, a real USB hub, native hotkeys, or device output.

Other desktop targets

  • Mac Catalyst: the project selects net10.0-maccatalyst on macOS. Build on macOS with the matching .NET/MAUI toolchain and Xcode. The project declares Mac Catalyst 18.0 as its supported platform minimum. Windows update packages do not apply.
  • Linux, experimental: the project selects net11.0 and uses the Avalonia MAUI backend with WebKitGTK. The checkout's scripts/publish-linux.sh selects the Linux build toolchain and outputs to artifacts/linux-x64. Review the script's SDK/workload requirements before running it; workload installation needs write access to the .NET installation. Runtime prerequisites include WebKitGTK 4.1 (libwebkit2gtk-4.1-0 on Debian/Ubuntu).

Automatic updates are Windows-only. Linux global hotkeys require X11 or XWayland; plugin native libraries must match the actual platform. These source targets do not imply that every plugin is supported on every desktop OS.

Build problems

  • SDK not found: run dotnet --list-sdks, compare with global.json, and install an accepted SDK. Do not change the target framework just to bypass it.
  • Missing workload or Windows SDK: restore the project workloads and install the Windows SDK named by the target framework.
  • NuGet restore failure: check the configured sources and network access. Confirm the SDK package version in the core project is available to your feed.
  • Styles missing after a change: rebuild the appropriate CSS bundle; running dotnet build alone does not regenerate Tailwind output.
  • Second app fails to start or output doubles: close the other copy. Both use the same settings, flows, and device connections.

Use logs and diagnostics for problems that occur after the build starts successfully.

Contributors

Thank you to everyone who has helped improve this documentation.

bwmpbwmp