Entry points and wrappers

flowchart TD
    entryWslLaunch[launch.sh] --> entryWslBuild[build-if-needed.sh]
    entryWindowsLaunch[launch-windows.sh] --> entryWindowsBuild[build-if-needed.sh]
    entryWslBuild --> entryShadedLauncher[Shaded Java launcher]
    entryWindowsBuild --> entryPowerShell[launch.ps1]
    entryPowerShell --> entryShadedLauncher
    entryShadedLauncher --> entryMinecraftChild[Java 25 Minecraft child]

Direct Java installation pipeline

flowchart TD
    pipelineMain[Main.java] --> pipelineDefinitions[distributions.toml catalog]
    pipelineDefinitions --> pipelineDistribution[Selected distribution]
    pipelineDistribution --> pipelineVersions[Minecraft and Fabric versions]
    pipelineVersions --> pipelineMojang[Mojang manifest]
    pipelineVersions --> pipelineFabricMeta[Fabric Meta]
    pipelineDistribution --> pipelineArtifacts[Local or remote artifacts]
    pipelineArtifacts --> pipelineValidation[SHA-512 validation]
    pipelineValidation --> pipelineGame[Per-distribution game]
    pipelineMojang[Mojang manifest] --> pipelineVersionMetadata[Version metadata]
    pipelineVersionMetadata --> pipelineAssets[Assets]
    pipelineAssets --> pipelineSharedState[Shared state]
    pipelineFabricMeta[Fabric Meta] --> pipelineMaven[Maven repositories]
    pipelineMaven --> pipelineSharedState
    pipelineGame --> pipelineInstance[Launched instance]
    pipelineSharedState --> pipelineInstance

Platform/state split

flowchart LR
    platformLinuxState[state/linux] --> platformWslState[WSL runtime state]
    platformWslState --> platformZink[Mesa Zink]
    platformZink --> platformLlvmpipe[Vulkan llvmpipe limitation]
    platformWindowsSymlink[state/windows symlink] --> platformNtfs[NTFS Windows state]
    platformNtfs --> platformWindowsJava[Windows Java runtime]
    platformWindowsJava --> platformNvidia[NVIDIA Vulkan]
    platformNvidia --> platformRtx[RTX 4090]

Distribution selection

flowchart TD
    selectionWslExample[./launch.sh aperture-26.3-s7] --> selectionCatalog[Distribution catalog selection]
    selectionWindowsExample[./launch-windows.sh iris-1.21.10] --> selectionCatalog
    selectionWindows262[./launch-windows.sh 26.2-iris] --> selectionCatalog
    selectionCatalog --> selectionDistribution[Selected distribution]
    selectionCatalog --> selection262[26.2-iris]
    selection262 --> selection262Minecraft[Minecraft 26.2]
    selection262 --> selection262Fabric[Fabric 0.19.3]
    selection262 --> selection262Iris[Iris 1.11.2]
    selection262 --> selection262Sodium[Sodium 0.9.1]
    selectionDistribution --> selectionGames[Isolated game directories]
    selectionAssets[Shared assets] --> selectionGames
    selectionLibraries[Shared libraries] --> selectionGames

The default distribution, versions, backend, and Modrinth/remote/file artifacts are defined in the project-root distributions.toml; edits are picked up without changing Java factory code. Set MC_DISTRIBUTIONS_FILE to select another catalog. File artifact source/destination paths support $SOURCE_DIR for the repository root and $DISTRIBUTION_BASE for the selected installed distribution root.

Direct-world launch

./launch-windows.sh 26.2-iris --world ShaderTestWorld
./launch.sh 26.2-iris --world ShaderTestWorld

MC_WORLD is an equivalent fallback. The value is the save-folder name under the selected distribution's game/saves.

Microsoft account authentication

The launcher uses Microsoft OAuth device-code login. It caches the refresh token and short-lived Minecraft session under the selected platform state's shared/auth/microsoft.toml, refreshes them automatically, and never prints tokens.

To set up authentication, register or use a public-client Microsoft identity application that permits personal Microsoft accounts and device-code flow. Set MC_MICROSOFT_CLIENT_ID, then run:

./launch-windows.sh login
./launch.sh login

Follow the printed browser and code prompt. Subsequent launches use the cache automatically. Use --offline to bypass it, or --microsoft to force Microsoft authentication and log in interactively if needed. The corresponding ./launch-windows.sh logout and ./launch.sh logout commands delete the local cache. The account must own Minecraft: Java Edition.

Wisdom shader development link

flowchart TD
    wisdomGithub[GitHub Wisdom-Shaders master] --> wisdomLinuxClone[state/linux/shared/shader-sources<br/>shallow clone]
    wisdomGithub --> wisdomWindowsClone[state/windows/shared/shader-sources<br/>shallow clone]
    wisdomLinuxClone --> wisdomCompatibility[8899fc0 compatibility]
    wisdomCompatibility --> wisdomHalfPrecision[538516e explicit half precision]
    wisdomHalfPrecision --> wisdomFullPrecision[1bdcbce full-precision opt-out]
    wisdomWindowsClone --> wisdomCompatibility
    wisdomLinuxClone --> wisdomLinuxAperture[state/linux/distributions/aperture-26.3-s7/game/shaderpacks/Wisdom-Shaders]
    wisdomLinuxClone --> wisdomLinuxIris[state/linux/distributions/iris-1.21.10/game/shaderpacks/Wisdom-Shaders]
    wisdomLinuxClone --> wisdomLinux262Iris[state/linux/distributions/26.2-iris/game/shaderpacks/Wisdom-Shaders]
    wisdomWindowsClone --> wisdomWindowsAperture[state/windows/distributions/aperture-26.3-s7/game/shaderpacks/Wisdom-Shaders]
    wisdomWindowsClone --> wisdomWindowsIris[state/windows/distributions/iris-1.21.10/game/shaderpacks/Wisdom-Shaders]
    wisdomWindowsClone --> wisdomWindows262Iris[state/windows/distributions/26.2-iris/game/shaderpacks/Wisdom-Shaders]
    wisdomLinuxIris --> wisdomIris[Iris selects Wisdom-Shaders]
    wisdomWindowsIris --> wisdomIris
    wisdomIris --> wisdomTest[Remote Creative Test]
    wisdomFullPrecision --> wisdomMasterRender[Wisdom master 26.1 render]
    wisdomGithubV3[GitHub Wisdom-Shaders V3 tip<br/>3790f22 Iris warnings and interfaces] --> wisdomV3Render[Wisdom V3 26.1 render]
    wisdomHalfPrecision --> wisdomCapability{Half capability}
    wisdomCapability --> wisdomExt[Standard EXT float16]
    wisdomCapability --> wisdomNvidia[NVIDIA NV_gpu_shader5]
    wisdomCapability --> wisdomAmd[AMD extension]
    wisdomCapability --> wisdomFallback[Full-float fallback]