[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-105443":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":9,"trendingCount":15,"starSnapshotCount":15,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},105443,"VSCode-minecraft-workbench","lopleec\u002FVSCode-minecraft-workbench","lopleec","A VSCode Extensions that can download and launch Minecraft.",null,"TypeScript",130,20,1,4,0,43,129,84.07,"MIT License",false,"main",true,[],"2026-11-01 00:16:54","# Minecraft Workbench\n\nA Minecraft Java Edition launcher, mod development workspace and server manager for VS Code.\n\n[Releases](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Freleases\u002Flatest) · [简体中文](#简体中文) · [中文使用说明](README.zh-CN.md) · [MIT License](LICENSE)\n\nNative sidebar views, commands, settings, tasks and output channels keep the extension at home in VS Code. Editor pages follow your theme, including light, dark and high contrast. The default language follows VS Code; English and Simplified Chinese can also be selected manually.\n\n![Modrinth discovery in VS Code with the Dark Modern theme](docs\u002Fimages\u002Fdiscover-dark.png)\n\n## Requirements and installation\n\n- Desktop VS Code **1.96 or later**. Minecraft **Java Edition** only.\n- A compatible Java runtime for the selected game version; use **Java → Detect Local Java** or **Download JDK**. Mod development requires a JDK.\n- Internet access for initial downloads. A fully installed instance can launch with an offline account without refreshing the version manifest.\n- In SSH, WSL or container workspaces, files and processes live on the **extension host machine**. Launching a game there requires a graphical session.\n\n1. Open the [latest release](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Freleases\u002Flatest).\n2. Under **Assets**, download `minecraft-workbench-\u003Cversion>.vsix`.\n3. In VS Code, run **Extensions: Install from VSIX…** and select the downloaded file.\n4. Reload VS Code if prompted, then open **Minecraft** in the activity bar.\n\nUse a trusted workspace to enable operations that download files or run processes. Development builds are available from successful [CI runs](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Factions\u002Fworkflows\u002Fci.yml) under **Artifacts → minecraft-workbench-vsix**; unzip the artifact before installing its VSIX.\n\nInstalling the VSIX does not require a separate Node.js installation; the extension uses VS Code's bundled runtime. Building and packaging from source requires Node.js **22 or later** because the packaging tools depend on it:\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench.git\ncd VSCode-minecraft-workbench\nnpm ci\nnpm run package\n```\n\nInstall the generated `.vsix` using the same steps above.\n\nThe publisher is `Lopleec`; the extension ID is `Lopleec.minecraft-workbench`. If upgrading from the old `minecraft-workbench.minecraft-workbench` development build, uninstall that build before installing this one. Existing default storage is detected and reused. Microsoft accounts must sign in again because SecretStorage is scoped to the extension ID.\n\n### Extension updates\n\nFor GitHub\u002Fmanual VSIX installations, use **More → Check for extension updates**. Checks run only when clicked. If a newer stable release is available, open its download link or release notes, or choose **Download and install** in a local desktop window. Installation verifies the published SHA-256, extension identity, version and VS Code requirement. Reloading requires a separate click and is blocked while a game or server is running.\n\nTurn off `minecraftWorkbench.updates.enabled` to hide the entry and disable\u002Fcancel checks. There are no startup checks, timers or silent installations. Marketplace installations keep VS Code’s own update handling. VS Code does not provide a public installation-source API; this feature reads local installation metadata. Unknown sources and remote windows use manual download links instead of in-place installation. A VSIX record identifies a manual installation, not the website it was downloaded from.\n\n### First use and agreements\n\nThe first run opens **Agreements & About**. Read the linked [Minecraft EULA](https:\u002F\u002Fwww.minecraft.net\u002Fen-us\u002Feula) and the extension's [terms and notices](TERMS.md), then check both boxes and select **Accept and continue**. Both start unchecked. Choosing **Not now** closes the page and leaves extension operations unavailable.\n\nOnly agreement reading, language selection, confirmation and closing remain available; all other extension commands and operations stay locked. The sidebar Language command can still change the extension-wide preference before acceptance.\n\nThe page defaults to following the extension language. Its manual language selector changes only this page, leaving the extension, sidebar and VS Code preferences unchanged. The extension itself follows VS Code by default.\n\n![First-use agreements in VS Code](docs\u002Fimages\u002Fagreements-en.png)\n\nThe confirmation stores only the notice version, time and two choices locally in the VS Code profile. Updated extension notices require confirmation again; the notice version is not a Mojang EULA version. **Agreements & About** remains available from the sidebar and Command Palette. This confirmation adds no restrictions to MIT and does not grant a Minecraft game license.\n\n## Launcher Mode\n\n1. Open **Instances → New instance**. Choose a name, game version, loader and parent directory.\n2. Add an offline account in **Manage → Accounts**, or configure Microsoft sign-in below.\n3. Detect, add or download Java from **Manage → Java**.\n4. Choose **Install \u002F Repair**, then **Launch**. You can also save an instance first and install it later.\n\n![Instance installation form with April Fools versions](docs\u002Fimages\u002Finstall-dark.png)\n\nThe version list includes releases, snapshots and previews, April Fools versions, old Beta and old Alpha from Mojang's manifest. Vanilla, Fabric, Quilt, Forge and NeoForge are available where the selected version supports them. Loader prereleases are listed too. Change game or loader versions later, reinstall a loader, or repair a failed download from the instance pages.\n\n| Area | Available controls |\n| --- | --- |\n| Instances | Independent game directories, version switching, repair, duplicate with or without worlds, move directory, last played and playtime |\n| Launch | Per-instance account and Java, memory, GC, JVM and game arguments, window size, fullscreen, server auto-join |\n| Content | Modrinth mods, modpacks, resource packs and shaders; local JAR\u002FZIP imports; enable, disable, remove and update |\n| Worlds | Full `saves` backups, restore, optional backup before launch and retention limits |\n| Downloads | Progress, cancellation, retry, resumable files, published hash verification, mirrors and proxies |\n| Accounts and Java | Multiple offline\u002FMicrosoft\u002Fauthlib-injector accounts, account switching, local Java discovery and Eclipse Temurin downloads |\n\n### Repair an instance\n\nSelect an instance and choose **Install \u002F Repair** on its settings page, or run **Minecraft Workbench: Install \u002F Repair Instance**. The same repair engine handles Vanilla, Fabric, Quilt, Forge and NeoForge across supported Minecraft versions and imported official\u002FHMCL\u002FPCL, Prism\u002FMultiMC and Modrinth instances.\n\nRepair checks the client, libraries, asset index, assets and logging configuration against available metadata, restores missing or corrupt files and rebuilds loader outputs when required. Valid files are reused from disk\u002Fcache. The installed loader version stays pinned; repair does not update it. Extracted native libraries are rebuilt per instance. Worlds and configuration remain in place. Files with managed download\u002Fsource records are verified and restored; unrelated local mods, resource packs and shaders are retained.\n\nImported custom profiles keep readable settings. Missing official parent profiles can be downloaded again; known loader profiles can be regenerated. Original profiles are backed up under `\u003Cruntime>\u002F.workbench\u002Fprofile-backups\u002F` before replacement. An unknown custom profile with no recoverable metadata requires the original launcher or backup. Repair cannot reconstruct files for which no source or metadata is available.\n\n**Stop** works while an instance is installing or preparing to launch. The task notification also provides cancellation. The output shows Java selection, account preparation, file checks, native extraction and process startup. Shared-runtime installation tasks are queued so cancelling a waiting task cannot interrupt another repair.\n\n### Browse and manage content\n\nOpen **Content → Browse content**. Discover starts with the most downloaded projects, with icons, descriptions and download counts. Search or sort by relevance, followers, recent updates or newest releases. Choose an instance to apply Minecraft and loader compatibility filters.\n\n**Versions** lists a project's releases with game, loader and release-channel filters. **Show all versions** also reveals incompatible releases; installation into an incompatible instance stays blocked. Selecting a version opens a dependency review before installation.\n\n![Iris version selection and required dependency review](docs\u002Fimages\u002Fdependencies-dark.png)\n\nRequired dependencies resolve recursively. Optional dependencies can be included separately. Fabric and Quilt checks inspect `fabric.mod.json`, embedded modules, version ranges and declared incompatibilities. Forge and NeoForge use Modrinth declarations and game\u002Floader compatibility. Conflict checks help detect declared dependency problems, duplicate Fabric IDs and unreadable archives; they cannot predict every runtime or mixin conflict.\n\nThe **Installed** tab supports filtering, local imports, toggling files, removal and updates. Updates preserve disabled state and archive replaced files in `.workbench\u002Fhistory`. Shader packs require a compatible shader mod such as Iris or Oculus.\n\nUse **Instances → Import modpack** or **Installed → Import modpack…** to import Modrinth `.mrpack` files locally or download packs from Discover. Imports create a new instance and apply common\u002Fclient overrides, skipping server-only and optional client files. Export includes enabled content and configuration, with download references for recognized files and overrides for local files. Worlds, logs, server lists and account metadata are excluded. **CurseForge exported ZIPs** (`manifest.json` + overrides) are also supported. With online access off, use bundled files or select local JAR\u002FZIP files; reference-only manifests do not contain the mods, and offline import cannot verify their CurseForge file IDs.\n\n### CurseForge downloads (Beta)\n\nLocal CurseForge ZIP import is available by default. **Automatic CurseForge metadata and downloads are off by default**; enable `minecraftWorkbench.curseforge.enabled` in Settings to use them. Then run **Minecraft Workbench: Configure CurseForge API Key**, or use **Workbench → Settings → CurseForge API key**. The key is stored in SecretStorage and sent only to the official API\u002FCDN origins; it is not included in settings, URLs or exported pack records. See [API key access](https:\u002F\u002Fsupport.curseforge.com\u002Fsupport\u002Fsolutions\u002Farticles\u002F9000208346-about-the-curseforge-api-and-how-to-apply-for-a-key) and [CDN authentication](https:\u002F\u002Fblog.curseforge.com\u002Fintroducing-api-key-authentication-for-curseforge-file-downloads\u002F).\n\nBeta downloads use the pack's exact project\u002Ffile IDs and verify published hashes. Files whose authors disallow third-party downloads must be selected manually from their official pages and are checked against the original hash. Turning Beta off cancels active requests. Local imports and repairs using local files remain available, without API requests or a key. CurseForge profile codes and in-app share codes are not import formats.\n\nManaged Modrinth\u002FCurseForge pack files retain their download or local-source records for **Install \u002F Repair**. Disabled files stay disabled, user-updated mods keep their new versions, and files removed through the content manager stay removed. Local-only files require the original archive or selected source file when a replacement is needed.\n\n### Memory and instance settings\n\nMemory is adjusted **after creation**, in **Instance settings**, or globally in VS Code Settings. By default, minimum and maximum memory are `0` (automatic): the maximum uses **25% of system RAM**, rounded down to 128 MB and capped at 8 GiB; the minimum scales with it, usually 256–1024 MB. Change the percentage globally, or turn off **Use global memory settings** to set an instance's own limits. Explicit manual values take precedence.\n\nStop a running instance before changing its content, versions or restoring worlds. Restore automatically backs up the current worlds first. Deleting an owned instance moves its instance folder to the operating system trash when supported. Removing an instance managed in place keeps its files.\n\nJava selection uses the **instance override → global default → automatic detection\u002Fdownload** order. Instance Java is optional. Changing other instance settings preserves an existing override; clear the instance field to return to the global default.\n\n## Existing instances and storage\n\nNew instances use the **Prism \u002F MultiMC format**: a named folder containing `instance.cfg`, `mmc-pack.json`, and a `.minecraft` game directory. World saves remain ordinary Java Edition worlds in `saves\u002F\u003Cworld>\u002F`. Shared Minecraft versions, libraries and assets use the system Minecraft directory; `minecraftWorkbench.gameDirectory` changes that location. `minecraftWorkbench.instanceDirectory` selects the instances parent and can point to an existing PrismLauncher `instances` directory. Existing Workbench directories continue to work.\n\nOpen **Instances → Import instance** to scan a Minecraft\u002FHMCL\u002FPCL directory, a Prism\u002FMultiMC instances folder, a Modrinth profile folder, or a ZIP export. The preview shows detected Minecraft and loader versions. **Manage in place** keeps the original files and shares changes with the original launcher; removing that registration keeps its files. **Copy** creates a separate Prism\u002FMultiMC instance with mods, configuration and worlds. Launcher hooks and account databases are not imported. Missing resources are repaired on first launch.\n\n**Export Instance** creates a Prism\u002FMultiMC ZIP, optionally including worlds. **Import Modpack** and **Export .mrpack** use the [Modrinth pack format](https:\u002F\u002Fsupport.modrinth.com\u002Fen\u002Farticles\u002F8802351-modrinth-modpack-format-mrpack). Current Modrinth App installations without a `profile.json` should be exported as `.mrpack` first. Legacy jar mods and unrecognized MultiMC components are reported instead of silently dropped. Launcher-specific profile patches require copying and rebuilding a supported loader. For ZIPs over 512 MB, extract or copy the instance folder directly.\n\n**World backups → Import worlds \u002F Export world** accepts standard Java world folders and ZIPs, including worlds from other launchers. Existing world names create a separate numbered copy. Bedrock `.mcworld` files require conversion and are not Java world imports.\n\nMinecraft language initially follows the extension language, which follows VS Code by default. The automatic setting preserves a language chosen in-game. Override it in the instance settings or `minecraftWorkbench.gameLanguage` (`auto`, `preserve`, or a Minecraft code such as `en_us`, `zh_cn`).\n\n## Accounts and Microsoft sign-in\n\nExternal authentication is available under **Accounts → External authentication**. Enter an HTTPS Yggdrasil API address, such as LittleSkin's `https:\u002F\u002Flittleskin.cn\u002Fapi\u002Fyggdrasil`, then enter credentials in VS Code and select a player profile. ALI discovery is supported. Tokens stay in SecretStorage; passwords are not saved. Before launch, tokens are validated\u002Frefreshed and the SHA-256-verified authlib-injector agent is downloaded when needed. External identities authenticate only to servers configured for that provider.\n\nBefore entering credentials, confirm the full resolved authentication API address in the native risk dialog. The provider receives your username and password and issues the tokens; use a separate password and never enter your Microsoft password. HTTPS does not establish provider trust. Removing an account deletes local credentials; revoke access with the provider when needed. No provider is preselected. [Third-party services and licenses](THIRD_PARTY_NOTICES.md) lists service terms, privacy links and separately downloaded components.\n\n\n**No Microsoft Client ID is bundled.** Leave it empty to use offline accounts. Offline identities do not authenticate to servers that require Microsoft\u002FMinecraft authentication.\n\nFor Microsoft sign-in, enter your own public-client application ID in **Manage → Accounts** or `minecraftWorkbench.microsoftClientId`. It must support device code flow, personal Microsoft accounts, Xbox sign-in and Minecraft Services access. An application ID alone does not guarantee Minecraft Services approval. No client secret is needed or collected.\n\nSign-in uses Microsoft's device login page. Refresh and Minecraft access tokens are stored in **VS Code SecretStorage**, refreshed before expiry and before launch. A failed refresh requires signing in again. Removing an account deletes its saved credentials. Account names and UUIDs are local metadata. The extension collects no telemetry.\n\n## Terracotta multiplayer (Beta)\n\nThis optional feature is **off by default**. Enable `minecraftWorkbench.terracotta.enabled` in Settings, then open **More → Terracotta (Beta)**. Read the upstream license and multiplayer notice and confirm both checkboxes before downloading or running the component. Notice language can be switched independently of the extension language.\n\n1. Download the official Terracotta component, or choose an existing official executable. Downloads use a pinned supported release and its published SHA-256 digest. On macOS, open the official installer to set up its background component before connecting.\n2. Connect the component. A host opens a Minecraft world to LAN and selects **Create room**; a guest enters the Terracotta room code and selects **Join room**.\n3. Guests can copy the game address or launch the selected instance into the joined room. The temporary address does not replace the instance's saved server setting.\n4. Leave the room when finished. Disabling the setting or revoking confirmation disconnects rooms opened through this extension. Custom public nodes can be configured with `minecraftWorkbench.terracotta.publicNodes`.\n\n[Terracotta](https:\u002F\u002Fgithub.com\u002Fburningtnt\u002FTerracotta) is a separate program by Burning_TNT and contributors, licensed under AGPL-3.0-or-later with the upstream exception. It is used unmodified through its local HTTP interface and is not bundled into the extension. The current Beta targets Terracotta's 0.4 API and Java Edition LAN worlds. NAT traversal and relay availability depend on the participants' networks and the external service. Room codes grant access to their room; share them only with intended players.\n\n## Server Mode\n\nChoose **Server** in the mode selector, then **Servers → New server**. Select software, Minecraft\u002Fsoftware version and a build. **Create and start** downloads the server, detects or downloads the required JDK and starts it. You can choose installation only, or create the entry and install later. The first game-server start asks you to accept the Minecraft EULA.\n\n![Server installation in VS Code](docs\u002Fimages\u002Fserver-create-dark.png)\n\nSupported software: **Vanilla, Paper, Purpur, Folia, Fabric, Quilt, Forge, NeoForge and Velocity**. **Custom JAR** creates a directory where you can import an executable server JAR. Availability follows each project's published versions; not every historical Minecraft version has a dedicated server. Experimental builds require an explicit selection.\n\n**Console & settings** contains the console, commands, normal stop\u002Frestart, Java and memory settings, server properties, version changes, repair and world backups. Stop before editing content or restoring worlds. Normal stop sends the server's save\u002Fshutdown command; force stop asks for confirmation. A server can be removed from the list while retaining its files.\n\n![Paper console and controls in VS Code](docs\u002Fimages\u002Fserver-console-dark.png)\n\n**Discover** and **Installed** use the selected server. Paper\u002FPurpur list compatible Bukkit, Spigot and Paper plugins; Folia requires declared Folia support. Velocity filters for Velocity plugins. Fabric, Quilt, Forge and NeoForge use server mods. Modrinth versions, descriptions, icons, dependency review, updates, enable\u002Fdisable and removal use the same pages as client content. Client-only projects are rejected. Local JARs can be imported. Custom JAR entries have no inferred plugin\u002Fmod platform.\n\nNew game servers bind to `127.0.0.1` by default. Change **Settings → Network → Bind address** to `0.0.0.0` for LAN access. Firewall rules, router forwarding and public hosting are configured separately. Velocity is a proxy; configure its backend servers in `velocity.toml` using **Open configuration**.\n\n## AI tools over MCP\n\nMCP is **off by default**. Select **Workbench → Settings → Register MCP**, or enable `minecraftWorkbench.mcp.enabled`. On VS Code 1.101 or later, Minecraft Workbench appears in the MCP providers and chat tool picker. On VS Code 1.96–1.100, use **Settings → Copy MCP connection** to configure a compatible MCP client; the same tools and access controls are available. **Unregister MCP** removes the definition and closes the listener.\n\nTools cover instance creation and launch, game\u002Floader versions, Modrinth content and dependencies, accounts, Java, tasks, backups, Gradle projects, server management and extension settings. `workbench_state` lists the current entries. Operations requiring a file picker or confirmation open the native VS Code UI. AI tools cannot accept the first-use agreements; server EULA acceptance remains interactive.\n\nFor another MCP client, run **Copy MCP Connection** and adapt the copied Streamable HTTP configuration to that client's format. It contains a local URL and authorization header, valid for the current extension-host session. The listener accepts authenticated requests only on `127.0.0.1`; keep the copied header private. In remote workspaces it runs on the extension host. Tool results may contain local paths, project details and console logs; the connected AI client's data policy applies. Login tokens are never returned.\n\n## Developer Mode\n\nSwitch modes from the sidebar or status bar, then open **Manage → Projects**.\n\n![Fabric mod project creation using an official template](docs\u002Fimages\u002Fprojects-dark.png)\n\n1. Select **Fabric**, **Forge** or **NeoForge** and an official template\u002FMDK version.\n2. Enter the mod name, mod ID, Java package and project directory. The editable package suggestion uses `com.example.\u003Cmod_id>`.\n3. Create the project. It opens automatically unless you disable that option. Existing projects with a Gradle wrapper can also be imported.\n4. Use project actions to **build**, **clean**, **run the client**, **generate sources \u002F IDE files** and view build artifacts.\n5. For debugging, choose **Run client for debugging**. Once Gradle is listening, choose **Attach debugger**. Install **Debugger for Java** when prompted; the default port is 5005.\n\nGradle runs through the project's wrapper in VS Code Tasks. The first run downloads Gradle and project dependencies. Templates define compatible game, loader and Gradle versions; historical versions may have no maintained template. This creates mod projects, not decompiled standalone game clients. Extension proxy settings apply to extension-managed downloads; Gradle repositories and proxies follow Gradle\u002Fproject configuration.\n\n## Settings, downloads and storage\n\nOpen **Minecraft Workbench: Settings** to see the native grouped Settings page. **Change Language**, the sidebar language item and the **EN \u002F 中** button switch language immediately. The extension language can be set independently from VS Code. The Workbench view keeps mode, language and Settings visible. Views retain VS Code's draggable dividers and native scrolling. Use **Workbench → … → Show Sidebar View** to reveal and focus a hidden or off-screen section. The collapsed **More** group contains Java, tasks, logs and agreements. Expand **Settings** for proxy credentials, MCP, storage and documentation; clicking its label opens the native Settings page.\n\n```json\n{\n  \"minecraftWorkbench.language\": \"en\",\n  \"minecraftWorkbench.minMemory\": 0,\n  \"minecraftWorkbench.maxMemory\": 0,\n  \"minecraftWorkbench.memoryPercentage\": 25,\n  \"minecraftWorkbench.sources\": {\n    \"manifest\": \"official\",\n    \"assets\": \"bmclapi\",\n    \"libraries\": \"bmclapi\"\n  }\n}\n```\n\n- **Download sources:** choose `official`, `bmclapi` or an HTTPS base per resource type: `manifest`, `client`, `server`, `assets`, `libraries`, `loader`, `modrinth`, `java`, `project`. Custom bases preserve the original path\u002Fquery. BMCLAPI applies only to supported endpoints; failed mirrors fall back to the original source. Authentication always uses official endpoints.\n- **Proxy:** HTTP, HTTPS, SOCKS5 and SOCKS5h are supported. SOCKS5 resolves names locally; SOCKS5h resolves through the proxy. An empty setting falls back to VS Code `http.proxy`. Use **Workbench → Settings → Proxy credentials** to save credentials in SecretStorage. Reload after network or storage changes.\n- **Reuse and speed:** verified files share a content-addressed cache across instances. Existing isolated runtimes can seed it after checksum verification. Reusing a version copies its verified files and downloads only missing or changed resources. Files of at least 16 MiB use up to four HTTP Range connections with 8 MiB segments; the global connection limit defaults to six. Completed segments survive retries, and unsupported hosts fall back to a single connection. Configure `sharedDownloadCache`, `downloadConnectionsPerFile`, `downloadChunkSize` and `downloadConcurrency`. Instance files are independent copies, so edits cannot change the shared cache.\n- **Download recovery:** `.part` files and HTTP Range validators allow resuming when the server supports it. A server ignoring ranges restarts the file. Published Minecraft\u002FModrinth hashes and JDK SHA-256 checks verify downloads.\n- **Directories:** storage, game, server and project locations are configurable. New instance metadata follows Prism\u002FMultiMC; `.workbench` holds only auxiliary content indexes, history and backups. Older instances may keep their existing `.runtime` directory.\n- **Process downloads:** these settings cover extension-managed downloads. Gradle and server bootstrappers\u002Finstallers can make additional downloads under their own configuration.\n- **Diagnostics:** use **Show Output** or **Open Game Log**. Extension output redacts authentication tokens and proxy credentials. Review external game\u002Fmod logs before sharing them.\n\n## Development and validation\n\n```sh\nnpm ci\nnpm test\nnpm run format:check\nnpm run legal -- --check\nnpm run compile\nnpm run test:host\nnpm run test:compat\nnpm run package\n```\n\nPress **F5** to open an Extension Development Host. Unit tests cover path safety, state persistence and recovery, accounts, range downloads, hashes, dependency resolution, backups and project customization. CI checks formatting, tests, compilation and packaging on Linux, Windows and macOS.\n\nHost tests require network access and a local or downloadable VS Code. `VSCODE_EXECUTABLE` selects a local executable; `MW_LIVE_INSTALL=1` also downloads a test Fabric instance. Microsoft sign-in needs an approved application and account and is not exercised automatically. Game launch, Gradle builds and installation\u002Fstart\u002Fstop of Paper, Fabric, Quilt, Forge and NeoForge 1.21.4 servers have been checked on macOS Apple Silicon; other platforms and every historical game\u002Floader combination have not been manually verified.\n\n`npm run test:compat` checks extension activation, consent, mode switching and MCP against the minimum supported VS Code in an isolated profile.\n\nScreenshots show the running extension in VS Code with sample instances and live Modrinth metadata. Project icons and descriptions belong to their respective authors.\n\n## Feedback and contributions\n\nBug reports, feature requests, translations and pull requests are welcome.\n\n- **Bugs:** search [existing issues](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fissues) first, then [open an issue](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fissues\u002Fnew). Include reproduction steps, expected and actual behavior, extension and VS Code versions, operating system and architecture. For game issues, include the Minecraft, loader and Java versions, relevant mods and a short log excerpt.\n- **Feature requests:** describe the use case and the workflow you would like to improve in an [issue](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fissues\u002Fnew). Screenshots or small examples help explain UI suggestions.\n- **Pull requests:** fork the repository, create a branch and keep the change focused. Explain the problem, the change and how it was checked. Discuss substantial changes in an issue first. Follow the existing code style, update both languages when changing UI text or documentation, and include screenshots for UI changes. Run the relevant checks listed above before opening a [pull request](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fpulls).\n\nRemove tokens, proxy credentials, account details and personal paths from shared logs and screenshots. Keep downloaded game files, worlds, local instance data and generated VSIX files out of source contributions. Contributions are licensed under the project's [MIT License](LICENSE); third-party content retains its own license.\n\n## License and acknowledgements\n\n[MIT](LICENSE), Copyright © 2026 Lopleec. Bundled dependency licenses are included in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt).\n\nBuilt with the [VS Code API](https:\u002F\u002Fcode.visualstudio.com\u002Fapi), [XMCL](https:\u002F\u002Fxmcl.app\u002Fen\u002Fcore\u002F), [Modrinth API](https:\u002F\u002Fdocs.modrinth.com\u002Fapi\u002F), and official [Fabric](https:\u002F\u002Fdocs.fabricmc.net\u002Fdevelop\u002Fgetting-started\u002Fcreating-a-project), [Forge](https:\u002F\u002Fdocs.minecraftforge.net\u002Fen\u002Flatest\u002Fgettingstarted\u002F) and [NeoForge](https:\u002F\u002Fdocs.neoforged.net\u002Fdocs\u002Fgettingstarted\u002F) templates. Independent of Mojang, Microsoft, Modrinth and the loader projects. Game files, accounts and downloaded content retain their respective terms and licenses.\n\n---\n\n## 简体中文\n\n在 VS Code 中启动 Minecraft Java 版、管理实例并开发模组。使用原生侧栏、命令、设置、任务和输出窗口；编辑器页面适配深色、浅色与高对比主题。默认跟随 VS Code 语言，也可单独手动选择英文或简体中文。\n\n### 安装与开始使用\n\n需要桌面版 **VS Code 1.96+**，仅支持 **Minecraft Java 版**。游戏所需 Java 可在插件中检测、手动添加或下载；开发模组需要 JDK。首次下载需要网络，完整安装后可使用离线账户启动，无需重新获取版本清单。\n\n1. 打开 [最新 Release](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Freleases\u002Flatest)。\n2. 在 **Assets** 中下载 `minecraft-workbench-\u003C版本号>.vsix`。\n3. 在 VS Code 中执行 **扩展：从 VSIX 安装…**，选择下载的文件。\n4. 按提示重新加载 VS Code，然后打开活动栏中的 **Minecraft**。\n\n下载和启动进程需要受信任的工作区。开发构建可从成功的 [CI 运行](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Factions\u002Fworkflows\u002Fci.yml) 中下载 **Artifacts → minecraft-workbench-vsix**，解压后安装其中的 VSIX。\n\n安装 VSIX 不需要额外安装 Node.js，扩展使用 VS Code 自带的运行时。从源码构建、打包需要 **Node.js 22+**，这是打包工具链的要求：\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench.git\ncd VSCode-minecraft-workbench\nnpm ci\nnpm run package\n```\n\n生成的 `.vsix` 按上面的步骤安装。\n\nPublisher 为 `Lopleec`，扩展 ID 为 `Lopleec.minecraft-workbench`。从旧的 `minecraft-workbench.minecraft-workbench` 开发包升级时，请先卸载旧包。扩展会检测并复用原有默认存储；Microsoft 账户需要重新登录，因为 SecretStorage 按扩展 ID 隔离。\nSSH、WSL、容器中的文件和进程位于扩展宿主机器；在远程机器运行游戏需要图形环境。\n\n### 插件更新\n\nGitHub \u002F 手动 VSIX 安装可使用**更多 → 检查插件更新**。点击后才联网检查；有新的稳定版本时，可打开下载链接、更新说明，或在本地桌面窗口选择**下载并安装**。安装前校验发布的 SHA-256、扩展标识、版本与 VS Code 要求。重新加载仍需另行点击，游戏或服务端运行时不会执行。\n\n关闭 `minecraftWorkbench.updates.enabled` 可隐藏入口并禁用、取消检查。没有启动检查、定时检查或静默安装。Marketplace 安装继续由 VS Code 管理更新。VS Code 没有公开的安装来源 API，因此通过本地安装记录识别；来源不明或远程窗口提供手动下载链接。VSIX 记录只能识别手动安装，不能证明下载网站。\n\n### 首次使用与协议\n\n首次打开会显示 **协议与关于**。阅读链接中的 [Minecraft EULA](https:\u002F\u002Fwww.minecraft.net\u002Fen-us\u002Feula) 与插件的 [用户协议和声明](TERMS.md)，勾选两项后选择 **同意并继续**。两项默认均未勾选；选择 **暂不使用** 会关闭页面，插件操作保持不可用。\n\n未同意时仅开放协议阅读、语言选择、确认与关闭，其余插件命令和操作均锁定；侧栏“语言”仍可修改插件整体的语言。\n\n协议页默认跟随插件语言；手动选择只改变协议页，不修改插件、侧栏或 VS Code 的语言设置。插件整体默认跟随 VS Code。\n\n![首次使用协议确认界面](docs\u002Fimages\u002Fagreements-zh.png)\n\n仅将提示版本、确认时间和两项选择保存在本地 VS Code 配置中。插件提示更新后需重新确认；此版本号不代表 Mojang EULA 版本。之后可通过侧栏或命令面板的 **协议与关于** 再次查看。此确认不为 MIT 增加限制，也不授予 Minecraft 游戏许可。\n\n### 启动模式\n\n1. 打开 **实例 → 新建实例**，填写名称，选择游戏版本、加载器和父目录。\n2. 在 **管理 → 账户** 添加离线账户，或按下文配置 Microsoft 登录。\n3. 在 **管理 → Java** 检测、添加 Java 或下载 Eclipse Temurin JDK。\n4. 选择 **安装 \u002F 修复**，完成后启动。也可先保存实例，稍后安装。\n\n版本列表包含 Mojang 清单中的正式版、快照与预发布版、愚人节版本、旧 Beta 和旧 Alpha。支持对应游戏版本可用的 Vanilla、Fabric、Quilt、Forge、NeoForge，以及 Loader 测试版本。创建后可以更改游戏版本、更新或重装 Loader，失败后可修复重试。\n\n| 功能 | 支持内容 |\n| --- | --- |\n| 实例 | 独立游戏目录、版本切换、修复、复制（可选存档）、移动目录、上次启动与游戏时长 |\n| 启动 | 独立账户与 Java、内存、GC、JVM \u002F 游戏参数、窗口尺寸、全屏、自动加入服务器 |\n| 内容 | Modrinth 模组、整合包、资源包、光影；导入本地 JAR\u002FZIP；启用、禁用、删除、更新 |\n| 存档 | 完整 `saves` 备份与恢复、可选启动前备份、保留数量 |\n| 下载 | 进度、取消、重试、断点续传、哈希校验、镜像与代理 |\n| 账户与 Java | 多离线 \u002F Microsoft 账户切换、本地 Java 检测、Temurin 下载 |\n\n### 修复实例\n\n选择实例，在设置页点击 **安装 \u002F 修复**，或执行 **Minecraft Workbench：安装 \u002F 修复实例**。Vanilla、Fabric、Quilt、Forge、NeoForge 的受支持版本，以及从官方\u002FHMCL\u002FPCL、Prism\u002FMultiMC、Modrinth 导入的实例，都使用同一套修复流程。\n\n修复会按可用元数据校验客户端、依赖库、资源索引、资源和日志配置，补齐缺失、损坏文件，必要时重新生成 Loader 输出；有效文件直接复用本地文件或缓存。保持已安装的 Loader 版本，不执行升级。解压后的本地库按实例重建，存档与配置保留；具有下载或来源记录的文件会校验、恢复，其余本地模组、资源包和光影保留。\n\n导入实例保留可读的自定义版本配置。缺失的官方父版本配置可以重新下载，已知 Loader 配置可以重建；替换前的配置备份位于 `\u003C运行目录>\u002F.workbench\u002Fprofile-backups\u002F`。无法识别且没有可恢复元数据的自定义配置，需要从原启动器或备份恢复。没有来源和元数据的文件无法凭空重建。\n\n实例安装中、启动准备中均可点击 **停止**，任务通知也提供取消。输出显示 Java 选择、账户准备、文件校验、本地库解压和进程启动阶段。共享运行目录的安装任务排队执行，取消等待任务不会中断其他修复。\n\n\n### 内容浏览与依赖\n\n从 **内容 → 浏览内容** 打开页面。发现页默认按下载量展示项目图标、简介和下载数，也可搜索或按相关度、关注数、更新与发布时间排序。选择实例后，可按游戏版本和 Loader 筛选兼容内容。\n\n**版本** 支持游戏版本、Loader 和发布类型筛选；**查看全部版本** 会显示不兼容版本，但不能将它们安装进当前实例。选定版本后先查看依赖计划，再安装。必需前置递归解析，可选依赖可单独勾选。\n\nFabric \u002F Quilt 会读取 `fabric.mod.json`、内嵌模块、版本范围和声明的不兼容项；Forge \u002F NeoForge 使用 Modrinth 声明及游戏、Loader 兼容性信息。冲突检查可发现声明的依赖问题、重复 Fabric ID、损坏文件，不能预测所有运行时或 Mixin 冲突。\n\n**已安装** 页面支持筛选、导入本地文件、启用、禁用、删除和更新。更新保留禁用状态，旧文件存放在 `.workbench\u002Fhistory`。光影包需配合 Iris、Oculus 等兼容模组。\n\n可从 **实例 → 导入整合包** 或 **已安装 → 导入整合包…** 导入本地 `.mrpack`，也可从 Modrinth 安装，新建实例并应用公共及客户端覆盖文件，跳过仅服务端和客户端可选文件。导出包含已启用内容与配置：已识别文件使用下载引用，本地文件作为覆盖文件。排除存档、日志、服务器列表和账户元数据。同时支持 **CurseForge 导出的 ZIP**（`manifest.json` 与覆盖文件）。在线功能关闭时使用包内文件或选择本地 JAR\u002FZIP；只有引用的清单不包含实际模组，离线导入无法校验 CurseForge 文件 ID。\n\n### CurseForge 下载（Beta）\n\n默认可手动导入本地 CurseForge ZIP。**CurseForge 元数据与自动下载默认关闭**，需在设置中开启 `minecraftWorkbench.curseforge.enabled`；然后执行 **Minecraft Workbench：配置 CurseForge API 密钥**，或打开 **工作台 → 设置 → CurseForge API 密钥**。密钥保存在 SecretStorage，仅发送至官方 API\u002FCDN，不写入设置、URL 或导出的整合包记录。参见 [API 密钥申请](https:\u002F\u002Fsupport.curseforge.com\u002Fsupport\u002Fsolutions\u002Farticles\u002F9000208346-about-the-curseforge-api-and-how-to-apply-for-a-key) 与 [CDN 认证说明](https:\u002F\u002Fblog.curseforge.com\u002Fintroducing-api-key-authentication-for-curseforge-file-downloads\u002F)。\n\nBeta 按清单锁定的项目、文件 ID 下载并校验哈希。作者禁止第三方下载的文件，需从官方页面手动下载，再校验原始哈希。关闭 Beta 会取消进行中的请求；本地导入、使用本地文件修复仍可使用，无需 API 请求或密钥。不支持 CurseForge 分享码导入。\n\nModrinth \u002F CurseForge 整合包保留可管理文件的下载或本地来源记录，供 **安装 \u002F 修复** 使用；禁用状态保持不变，用户更新过的模组保留新版本，通过内容管理删除的文件不再恢复。仅有本地来源的文件需要保留原 ZIP 或所选源文件，才能在文件缺失时补回。\n\n### 内存、语言与实例设置\n\n内存在**创建后的实例设置**或全局设置中调整。默认最小、最大内存为 `0`（自动）：最大值取**系统内存的 25%**，向下取整到 128 MB，上限 8 GiB；最小值随之调整，通常为 256–1024 MB。可修改全局百分比，或取消 **使用全局内存设置**，为实例单独填写。手动值优先。\n\n![浅色主题下的中文实例设置](docs\u002Fimages\u002Fsettings-zh-light.png)\n\n通过侧栏 **语言**、命令面板 **切换语言** 或 **EN \u002F 中** 按钮即时切换。语言可独立于 VS Code 设置。\n\n修改内容、版本或恢复存档前需停止实例。恢复前自动备份当前存档。删除自有实例会将实例目录移至系统废纸篓（系统支持时）；移除原地管理的实例只取消登记，保留文件。\n\nJava 按**实例单独设置 → 全局默认 → 自动检测 \u002F 下载**选择。实例 Java 可留空；修改其他设置会保留已有的单独配置，清空实例字段才恢复使用全局默认。\n\n### 现有实例与存储\n\n新建实例统一使用 **Prism \u002F MultiMC 格式**：以实例名称建立目录，其中包含 `instance.cfg`、`mmc-pack.json` 和 `.minecraft` 游戏目录。世界存档仍是 `saves\u002F世界名称\u002F` 下的原生 Java 版存档。版本文件、运行库和资源使用系统 Minecraft 目录，也可通过 `minecraftWorkbench.gameDirectory` 更改。`minecraftWorkbench.instanceDirectory` 可单独指定实例父目录，包括现有的 PrismLauncher `instances` 目录。旧版工作台实例继续兼容。\n\n在 **实例 → 导入实例** 中扫描 Minecraft\u002FHMCL\u002FPCL 目录、Prism\u002FMultiMC 实例目录、Modrinth 档案目录或 ZIP 导出文件，预览会显示识别出的 Minecraft 和 Loader 版本。**原地管理**保留原目录，与原启动器共用文件，移除登记时保留游戏文件；**复制导入**创建独立的 Prism\u002FMultiMC 实例，保留模组、配置和世界存档。不会导入原启动器的执行钩子或账户数据库。缺失的运行资源在首次启动时补齐。\n\n**导出实例**生成 Prism\u002FMultiMC ZIP，可选包含世界存档；**导入整合包 \u002F 导出 .mrpack** 使用 [Modrinth 格式](https:\u002F\u002Fsupport.modrinth.com\u002Fen\u002Farticles\u002F8802351-modrinth-modpack-format-mrpack)。新版 Modrinth App 若未保留 `profile.json`，请先导出 `.mrpack`。旧式 Jar 模组、无法识别的 MultiMC 组件会明确提示，不会静默忽略。启动器专有补丁需要复制导入并重建受支持的 Loader。ZIP 超过 512 MB 时，请先解压或直接复制实例目录。\n\n**存档备份 → 导入 \u002F 导出世界存档**支持原生 Java 版世界目录和 ZIP，可使用其他启动器中的存档。同名世界另建编号副本。基岩版 `.mcworld` 需先转换格式。\n\n游戏语言首次跟随扩展，扩展默认跟随 VS Code。自动模式保留玩家在游戏中选择的语言；可在实例设置或 `minecraftWorkbench.gameLanguage` 中覆盖，取值为 `auto`、`preserve` 或 `en_us`、`zh_cn` 等 Minecraft 语言代码。\n\n### 账户与 Microsoft 登录\n\n**账户 → 外置登录**支持 authlib-injector。填写 HTTPS Yggdrasil API 地址，例如 LittleSkin 的 `https:\u002F\u002Flittleskin.cn\u002Fapi\u002Fyggdrasil`，在 VS Code 中输入凭据并选择角色。支持 ALI 地址识别；令牌保存在 SecretStorage，不保存密码。启动前校验、刷新令牌，需要时下载并进行 SHA-256 校验的 authlib-injector。外置账户只能用于配置了对应认证服务的服务器。\n\n输入凭据前，需在原生风险提示中核对识别后的完整认证 API 地址并确认。用户名、密码会发送给服务商，由其签发令牌；请使用独立密码，切勿填写 Microsoft 密码。HTTPS 不代表服务商可信。移除账户只删除本地凭据，如需撤销访问，请前往服务商处理。界面不预选服务商。[第三方服务与许可](THIRD_PARTY_NOTICES.md)列明服务条款、隐私链接及单独下载组件的许可。\n\n**插件不内置 Microsoft Client ID**；留空时使用离线账户。离线身份无法通过要求 Microsoft \u002F Minecraft 验证的服务器认证。\n\n正版登录需在 **管理 → 账户** 或 `minecraftWorkbench.microsoftClientId` 中填写自己的公共客户端应用 ID。应用必须支持设备代码流程、个人 Microsoft 账户、Xbox 登录并获得 Minecraft Services 访问许可；仅创建应用 ID 不保证获得 Minecraft Services 许可。不需要也不会收集客户端密钥。\n\n通过 Microsoft 设备登录页面授权。刷新令牌和 Minecraft 访问令牌存于 **VS Code SecretStorage**，到期前及启动前自动刷新；刷新失败需重新登录。移除账户会删除保存的凭据，账户名和 UUID 作为本地元数据保存。插件不收集遥测。\n\n### 陶瓦联机（Beta）\n\n此可选功能**默认关闭**。在设置中开启 `minecraftWorkbench.terracotta.enabled` 后，从 **更多 → 陶瓦联机（Beta）** 进入。下载和运行组件前需阅读上游许可及联机须知，分别勾选确认；须知语言可以单独切换，不更改扩展语言。\n\n1. 下载官方组件，或选择已有的官方可执行文件。下载固定支持版本并校验官方 SHA-256；macOS 需先打开官方安装包，配置其后台组件，再连接。\n2. 连接组件。房主将 Minecraft 世界开放到局域网后点击**创建房间**；访客填写陶瓦房间码并**加入房间**。\n3. 访客可复制游戏地址，或直接启动所选实例进入房间；临时地址不会覆盖实例原有的服务器设置。\n4. 结束后退出房间。关闭设置或撤回确认会断开本扩展创建的连接。可通过 `minecraftWorkbench.terracotta.publicNodes` 指定额外公共节点。\n\n[Terracotta \u002F 陶瓦联机](https:\u002F\u002Fgithub.com\u002Fburningtnt\u002FTerracotta) 是 Burning_TNT 及贡献者的独立项目，采用附带上游例外的 AGPL-3.0-or-later。插件通过本地 HTTP 接口调用未修改的官方程序，不将它打包进扩展。当前 Beta 面向陶瓦 0.4 接口及 Java 版局域网世界；穿透和中继可用性取决于各方网络与外部服务。请仅向希望加入的玩家分享房间码。\n\n### 开服模式\n\n在模式选择器中选择 **开服**，然后打开 **服务端 → 新建服务端**。选择服务端类型、Minecraft \u002F 软件版本和构建版本。**创建并启动** 会下载服务端、检测或下载所需 JDK，然后启动；也可选择仅安装或仅创建。首次启动游戏服务端时需要确认 Minecraft EULA。\n\n![服务端安装界面](docs\u002Fimages\u002Fserver-create-dark.png)\n\n支持 **Vanilla、Paper、Purpur、Folia、Fabric、Quilt、Forge、NeoForge、Velocity**。**自定义 JAR** 可创建独立目录并导入可执行服务端 JAR。版本以各项目发布列表为准，并非每个历史 Minecraft 版本都提供独立服务端；实验构建需明确选择。\n\n**控制台与设置** 包含输出、指令、正常停止和重启、Java 与内存、服务端属性、版本更换、修复和存档备份。编辑内容或恢复存档前需要停服。正常停服会发送保存与关闭指令；强制停止需确认。从列表移除服务端时会保留文件。\n\n![Paper 控制台与服务端管理](docs\u002Fimages\u002Fserver-console-dark.png)\n\n**发现** 与 **已安装** 使用当前服务端的兼容条件。Paper \u002F Purpur 可安装兼容的 Bukkit、Spigot、Paper 插件；Folia 仅接受明确声明支持 Folia 的版本；Velocity 筛选其对应插件。Fabric、Quilt、Forge、NeoForge 使用服务端模组。版本、简介、图标、前置预览、更新、启用、禁用和删除与客户端使用同一套页面；拒绝仅客户端项目，也可导入本地 JAR。自定义 JAR 不会自动推断插件或模组平台。\n\n新游戏服务端默认绑定 `127.0.0.1`。局域网访问可在 **设置 → 网络 → 绑定地址** 中改为 `0.0.0.0`。防火墙、路由器端口转发和公网托管需另行配置。Velocity 属于代理端，可通过 **打开配置文件** 编辑 `velocity.toml`，设置后端服务端。\n\n### AI 与 MCP\n\nMCP **默认关闭**。点击 **工作台 → 设置 → 注册 MCP**，或启用 `minecraftWorkbench.mcp.enabled`，VS Code 1.101 及以上可在 MCP 提供程序和聊天工具选择器中启用 Minecraft Workbench；1.96–1.100 使用 **设置 → 复制 MCP 连接** 配置支持 MCP 的客户端，工具和访问控制保持一致。**取消注册 MCP** 会移除服务定义并关闭监听。\n\n工具覆盖实例创建与启动、游戏及 Loader 版本、Modrinth 内容与前置、账户、Java、任务、备份、Gradle 项目、服务端管理和扩展设置。`workbench_state` 可获取当前列表。需要文件选择或确认的操作仍使用 VS Code 原生界面。AI 工具不能代替用户同意首次使用协议；服务端 EULA 也需要交互确认。\n\n其他 MCP 客户端可使用 **复制 MCP 连接**，按客户端格式填入复制的 Streamable HTTP 配置。配置包含本地 URL 与授权请求头，仅在当前扩展宿主会话中有效；请勿公开请求头。接口只监听 `127.0.0.1` 并检查授权。远程工作区中，接口运行在扩展宿主机器。工具结果可能包含本地路径、项目信息和控制台日志，并适用所连接 AI 客户端的数据政策；工具不会返回登录令牌。\n\n### 开发模式\n\n在侧栏或状态栏切换模式，打开 **管理 → 项目**。\n\n1. 选择 **Fabric \u002F Forge \u002F NeoForge** 和官方模板或 MDK 版本。\n2. 填写模组名称、ID、Java 包名和目录。包名建议使用通用的 `com.example.\u003Cmod_id>`，可自行修改。\n3. 创建后自动打开项目，也可关闭该选项；支持导入包含 Gradle wrapper 的已有项目。\n4. 项目操作支持构建、清理、启动客户端、生成源码 \u002F IDE 文件和查看构建产物。\n5. 调试时先选择 **启动客户端并等待调试**，待 Gradle 监听端口后 **附加调试器**。按提示安装 **Debugger for Java**，默认端口 5005。\n\nGradle 通过项目 wrapper 在 VS Code Tasks 中运行，首次会下载 Gradle 与依赖。模板提供对应的游戏、Loader 和 Gradle 版本，部分历史版本没有维护中的模板。生成的是模组项目，并非反编译后的独立游戏客户端。插件代理用于插件管理的下载；Gradle 的仓库与代理遵循项目及 Gradle 配置。\n\n### 网络、目录与诊断\n\n工作台保留模式、语言和设置；**更多** 默认收起，包含 Java、任务、日志和协议。展开 **设置** 可管理代理凭据、MCP、存储目录或查看文档；点击设置文字仍打开原生设置页。MCP 默认关闭。分类保留 VS Code 原生分栏、分隔线和滚动；在 **工作台 → … → 显示侧栏分类** 中可直接找回被隐藏或移到下方的分类。\n\n全局选项位于 **Minecraft Workbench：设置** 的原生分组中。\n\n```json\n{\n  \"minecraftWorkbench.language\": \"zh-cn\",\n  \"minecraftWorkbench.minMemory\": 0,\n  \"minecraftWorkbench.maxMemory\": 0,\n  \"minecraftWorkbench.memoryPercentage\": 25,\n  \"minecraftWorkbench.sources\": {\n    \"manifest\": \"official\",\n    \"assets\": \"bmclapi\",\n    \"libraries\": \"bmclapi\"\n  }\n}\n```\n\n- **下载源：** 可按 `manifest`、`client`、`server`、`assets`、`libraries`、`loader`、`modrinth`、`java`、`project` 设置 `official`、`bmclapi` 或 HTTPS 基地址。自定义地址保留原路径和查询参数；BMCLAPI 仅用于支持的端点。镜像失败回退原始地址，认证始终走官方端点。\n- **代理：** 支持 HTTP、HTTPS、SOCKS5、SOCKS5h；SOCKS5 本地解析域名，SOCKS5h 由代理解析。留空时沿用 VS Code `http.proxy`。使用 **工作台 → 设置 → 代理凭据** 将凭据存入 SecretStorage。修改网络、存储配置后需重载窗口。\n- **断点与校验：** 保留 `.part`，在服务器支持时使用 HTTP Range 和校验器续传；服务器忽略范围则重新下载。校验 Minecraft \u002F Modrinth 公布的哈希及 JDK SHA-256。\n- **目录：** 存储、游戏、服务端和项目目录可配置。新实例采用 Prism\u002FMultiMC 格式；`.workbench` 只保存内容索引、历史和备份等辅助数据。旧实例保留原有 `.runtime` 目录。\n- **日志：** 使用 **显示输出** 或 **打开游戏日志**。插件输出会隐藏认证令牌和代理凭据；分享外部游戏或模组日志前仍需检查内容。\n\n### 下载复用与并发\n\n带校验和的文件在实例间使用共享缓存，包括客户端、库、资源、服务端、JDK 和 Modrinth 文件。旧实例中的文件也会在校验后纳入缓存；相同版本只补缺失或不同的资源，实例文件保持独立副本。\n\n至少 16 MiB 的文件默认使用 4 个 HTTP Range 连接、每段 8 MiB；全局并发上限默认为 6。重试保留已完成分段，不支持分段的源自动回退单连接。可配置 `sharedDownloadCache`、`downloadConnectionsPerFile`、`downloadChunkSize`、`downloadConcurrency`。设置作用于插件管理的下载；Gradle、服务端引导程序和安装器可能另行下载其依赖。\n\n### 开发与验证\n\n```sh\nnpm ci\nnpm test\nnpm run format:check\nnpm run legal -- --check\nnpm run compile\nnpm run test:host\nnpm run test:compat\nnpm run package\n```\n\n按 **F5** 打开扩展开发宿主。单元测试覆盖路径安全、状态保存及失败恢复、账户、续传、哈希、依赖、备份和项目定制。CI 在 Linux、Windows 和 macOS 检查格式、测试、编译和打包。\n\n宿主测试需要网络与本地或可下载的 VS Code。`VSCODE_EXECUTABLE` 可指定本地程序，`MW_LIVE_INSTALL=1` 会额外下载安装 Fabric 测试实例。Microsoft 登录需要获批应用和账户，不自动测试。游戏启动和 Gradle 构建，以及 Paper、Fabric、Quilt、Forge、NeoForge 1.21.4 服务端的安装、启动和停服，已在 macOS Apple Silicon 验证；其他平台及所有历史游戏 \u002F Loader 组合尚未逐一人工验证。\n\n`npm run test:compat` 会在隔离配置中使用最低支持的 VS Code，检查激活、协议保护、模式切换和 MCP。\n\n截图来自 VS Code 中运行的插件，使用示例实例和实时 Modrinth 元数据。项目图标、简介属于各自作者。\n\n### 反馈与贡献\n\n欢迎提交问题、功能建议、翻译改进和 Pull Request。\n\n- **问题反馈：** 请先搜索[已有 Issue](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fissues)，再[创建 Issue](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fissues\u002Fnew)。提供复现步骤、预期与实际表现、插件及 VS Code 版本、系统与架构。游戏相关问题请附上 Minecraft、Loader、Java 版本、相关模组和简短日志。\n- **功能建议：** 在 [Issue](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fissues\u002Fnew) 中说明使用场景和希望改善的操作流程。界面建议可附截图或小示例。\n- **提交 PR：** Fork 仓库并创建分支，每个 PR 聚焦一项改动，说明问题、修改内容和验证方式。较大改动建议先通过 Issue 讨论。遵循现有代码风格，修改界面文案或文档时同步更新中英文，界面改动附上截图。提交 [Pull Request](https:\u002F\u002Fgithub.com\u002Flopleec\u002FVSCode-minecraft-workbench\u002Fpulls) 前运行上文列出的相关检查。\n\n分享日志和截图前，请移除令牌、代理凭据、账户信息和个人路径。源码贡献中不要包含下载的游戏文件、存档、本地实例数据或生成的 VSIX。贡献采用项目的 [MIT License](LICENSE)，第三方内容保留各自许可。\n\n### 许可与致谢\n\n[MIT License](LICENSE)，Copyright © 2026 Lopleec。依赖许可见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 和 [THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt)。\n\n使用 VS Code API、XMCL、Modrinth API，以及 Fabric、Forge、NeoForge 官方模板。本项目独立于 Mojang、Microsoft、Modrinth 和各 Loader 项目。游戏文件、账户与下载内容仍适用各自条款和许可。\n\n### 界面示例\n\n![VS Code 中的 Modrinth 内容浏览](docs\u002Fimages\u002Fdiscover-dark.png)\n\n![包含愚人节版本的实例安装页面](docs\u002Fimages\u002Finstall-dark.png)\n\n![版本选择与依赖安装预览](docs\u002Fimages\u002Fdependencies-dark.png)\n\n![官方 Fabric 模板项目创建](docs\u002Fimages\u002Fprojects-dark.png)\n",2,"2026-10-31 04:26:48","CREATED_QUERY"]