Minecraft Workbench

A Minecraft Java Edition launcher, mod development workspace and server manager for VS Code.

Fork notice: This repository is maintained by ZIT Studio for BlockIDE and is derived from Lopleec/VSCode-minecraft-workbench. Launcher features come from upstream; see changes in this fork.

Java settings, Tasks and Output are separate entries under More. Projects belong to Developer Mode; each mode shows its own management pages. Separate Java and Tasks panes can be enabled with minecraftWorkbench.showRuntimeViews. The extension Settings page follows the extension language and also links to VS Code Settings.

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

Changes in this fork

This fork keeps the upstream feature set and adds BlockIDE integration:

Bundled Microsoft Client ID. A default Microsoft public-client Client ID is included, so Microsoft sign-in can be used without entering one first. Replace it in Tools → Accounts or minecraftWorkbench.microsoftClientId; clearing the setting disables Microsoft sign-in until an ID is provided. Offline accounts are unaffected.
BlockIDE build integration. The build script is .esbuild.mts. It resolves inputs and outputs from the script directory and produces the extension-host bundle (dist/extension.js) and the webview bundle (dist/workbench.js) for use as a built-in extension of BlockIDE.
Notices. LICENSE and the bundled dependency notices include ZIT Studio copyright alongside the upstream Lopleec notice.

Launcher, server, project and MCP features are otherwise unchanged and tracked from upstream. Standalone VSIX releases are published by the upstream project.

Requirements and installation

Desktop VS Code 1.96 or later. Minecraft Java Edition only.
A compatible Java runtime for the selected game version; use Java → Detect Local Java or Download JDK. Mod development requires a JDK.
Internet access for initial downloads. A fully installed instance can launch with an offline account without refreshing the version manifest.
In SSH, WSL or container workspaces, files and processes live on the extension host machine. Launching a game there requires a graphical session.

Open the latest release.
Under Assets, download minecraft-workbench-<version>.vsix.
In VS Code, run Extensions: Install from VSIX… and select the downloaded file.
Reload VS Code if prompted, then open Minecraft in the activity bar.

Use a trusted workspace to enable operations that download files or run processes. Development builds are available from successful CI runs under Artifacts → minecraft-workbench-vsix; unzip the artifact before installing its VSIX.

Installing 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:

git clone https://github.com/zitzhen/VSCode-minecraft-workbench.git
cd VSCode-minecraft-workbench
npm ci
npm run package

Install the generated .vsix using the same steps above.

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

Extension updates

For GitHub/manual 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.

Turn off minecraftWorkbench.updates.enabled to hide the entry and disable/cancel 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.

First use and agreements

The first run opens Agreements & About. Read the linked Minecraft EULA and the extension's terms and notices, then check both boxes and select Accept and continue. Both start unchecked. Choosing Not now closes the page and leaves extension operations unavailable.

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

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

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

Launcher Mode

Open Instances → New instance. Choose a name, game version, loader and parent directory.
Add an offline account in Tools → Accounts, or configure Microsoft sign-in below.
Detect, add or download Java from More → Java settings, or Tools → Java.
Choose Install / Repair, then Launch. You can also save an instance first and install it later.

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

Area	Available controls
Instances	Independent game directories, version switching, repair, duplicate with or without worlds, move directory, last played and playtime
Launch	Per-instance account and Java, memory, GC, JVM and game arguments, window size, fullscreen, server auto-join
Content	Modrinth mods, modpacks, resource packs and shaders; local JAR/ZIP imports; enable, disable, remove and update
Worlds	Full `saves` backups, restore, optional backup before launch and retention limits
Downloads	Progress, cancellation, retry, resumable files, published hash verification, mirrors and proxies
Accounts and Java	Multiple offline/Microsoft/authlib-injector accounts, account switching, local Java discovery and Eclipse Temurin downloads

Repair an instance

Select an instance and choose Install / Repair on its settings page, or run Minecraft Workbench: Install / Repair Instance. The same repair engine handles Vanilla, Fabric, Quilt, Forge and NeoForge across supported Minecraft versions and imported official/HMCL/PCL, Prism/MultiMC and Modrinth instances.

Repair 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/cache. 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/source records are verified and restored; unrelated local mods, resource packs and shaders are retained.

Imported 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 <runtime>/.workbench/profile-backups/ 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.

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.

Browse and manage content

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

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.

Required 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/loader compatibility. Conflict checks help detect declared dependency problems, duplicate Fabric IDs and unreadable archives; they cannot predict every runtime or mixin conflict.

The Installed tab supports filtering, local imports, toggling files, removal and updates. Updates preserve disabled state and archive replaced files in .workbench/history. Shader packs require a compatible shader mod such as Iris or Oculus.

Use 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/client 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/ZIP files; reference-only manifests do not contain the mods, and offline import cannot verify their CurseForge file IDs.

Use Install on a Discover → Mods result to install the matching version and required dependencies. For multiple mods, choose Batch install… and paste Modrinth links or IDs, or turn on Select multiple, select results and choose Install selected. Checkboxes are hidden until selection mode is enabled. Versions are matched to the selected Minecraft version and loader, with stable releases preferred. Review required dependencies and conflicts before installing; incompatible projects can be excluded. Required dependencies shared by several selected mods are installed once. Installed → Select multiple supports selecting filtered files and enabling, disabling or removing them together. Choose Auto layout, Side by side or Single pane in the content toolbar, or set minecraftWorkbench.contentLayout.

CurseForge downloads (Beta)

Local 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/CDN origins; it is not included in settings, URLs or exported pack records. See API key access and CDN authentication.

Beta downloads use the pack's exact project/file 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.

Managed Modrinth/CurseForge pack files retain their download or local-source records for Install / 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.

Memory and instance settings

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

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

Java selection uses the instance override → global default → automatic detection/download order. Instance Java is optional. Changing other instance settings preserves an existing override; clear the instance field to return to the global default.

Existing instances and storage

Use Open directory on an instance card or settings page to open its game files. Instance settings → Move instance moves the entire instance, including worlds and configuration, and supports moving between disks. Shared runtimes outside the instance remain in place. Linked instances must be duplicated before moving. World backups → Open saves directory opens saves directly.

New instances use the Prism / 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/<world>/. 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.

Open Instances → Import instance to scan a Minecraft/HMCL/PCL directory, a Prism/MultiMC 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/MultiMC instance with mods, configuration and worlds. Launcher hooks and account databases are not imported. Standard Minecraft/HMCL/PCL instances are marked as installed when their required runtime files are complete; missing resources are prepared as needed.

Export Instance creates a Prism/MultiMC ZIP, optionally including worlds. Import Modpack and Export .mrpack use the Modrinth pack format. 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. Standard HMCL patch profiles support in-place management without rewriting the original metadata. For ZIPs over 512 MB, extract or copy the instance folder directly.

World backups → Import worlds / 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.

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

Accounts and Microsoft sign-in

External authentication is available under Accounts → External authentication. Choose the LittleSkin preset or enter an HTTPS Yggdrasil API address, 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/refreshed and the SHA-256-verified authlib-injector agent is downloaded when needed. External identities authenticate only to servers configured for that provider.

Before 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 lists service terms, privacy links and separately downloaded components.

A default Microsoft public-client Client ID is bundled with this fork. Use it as-is, replace it with your own application ID in Tools → Accounts or minecraftWorkbench.microsoftClientId, or clear the setting to use offline accounts only. Offline identities do not authenticate to servers that require Microsoft/Minecraft authentication.

A custom application ID 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.

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

Terracotta multiplayer (Beta)

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

Select Download & set up to download the verified official Terracotta component, or choose an existing official executable. The page also provides an Official downloads link. Downloads use a pinned supported release and its published SHA-256 digest. On macOS, setup opens the official installer; complete it before connecting.
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.
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.
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.

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

Server Mode

Choose Server in the mode selector, then Servers → New server. Select software, Minecraft/software 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.

Supported downloads: Vanilla, Paper, Purpur, Folia, Fabric, Quilt, Forge, NeoForge and Velocity. Spigot, Bukkit and Custom JAR use a locally supplied 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.

Use Servers → Import server to manage an existing directory in place. Executable JARs and Forge/NeoForge argument files are detected without running startup scripts or reinstalling. Existing worlds, configuration and plugins stay in place. Imported eula.txt files do not replace the manual EULA confirmation in Console & settings → Agreements & licenses. AI tools cannot perform that confirmation.

Console & settings contains the console, commands, normal stop/restart, 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/shutdown command; force stop asks for confirmation. A server can be removed from the list while retaining its files.

The sidebar's Content, Discover and Installed use the selected server. Paper/Purpur list compatible Bukkit, Spigot and Paper plugins; Folia requires declared Folia support. Spigot and Bukkit use their matching plugin platforms. Velocity filters for Velocity plugins. Fabric, Quilt, Forge and NeoForge use server mods. Modrinth versions, descriptions, icons, dependency review, updates, enable/disable 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/mod platform.

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

AI tools over MCP

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

Tools cover instance creation and launch, game/loader 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.

One registration covers all three modes. Switching the UI mode does not remove tools or require reconnecting. Read workbench_state for IDs, then target the relevant entry:

Mode	MCP operations
Launcher	Instance creation, import, settings, repair and launch; content, accounts and world backups
Developer	`project_import`, `project_templates`, `project_create`, `project_configure`, `project_status`; `project_action` builds, runs, debugs, attaches, stops tasks and opens artifacts
Server	Server catalogs, creation/import, local JAR and plugin/mod import, settings, start/stop, console commands, logs and world backups

Use either instanceId or serverId for content operations. An explicit ID takes priority over the current UI mode; server content defaults to the software's mod/plugin platform. Developer Mode requires an explicit content target. Java, tasks and extension settings are shared across modes. Project imports keep files in place and open a window only with open=true.

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

Developer Mode

Switch to Developer Mode from the sidebar or status bar, then open Projects.

Select Fabric, Forge or NeoForge and an official template/MDK version.
Enter the mod name, mod ID, Java package and project directory. The editable package suggestion uses com.example.<mod_id>.
Create the project. It opens automatically unless you disable that option. Existing projects with a Gradle wrapper can also be imported.
Use project actions to build, clean, run the client, generate sources / IDE files and view build artifacts.
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.

Gradle 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/project configuration.

Expand Project settings for a project-specific Java executable, Gradle options and debug port. Empty Java and port 0 follow extension defaults; project values take priority. Missing JDKs are prepared automatically. Stop Gradle task stops a running build or test client, and Reload project metadata reads changes to gradle.properties. Re-importing a project updates its metadata while retaining its settings.

Settings, downloads and storage

Open Minecraft Workbench: Settings for settings in the extension language, with a link to VS Code Settings. Change Language and the sidebar language item switch language immediately. Editor pages use Tools for accounts, Java, tasks and settings; the target selector appears only on pages that use it. 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, Output and agreements. Expand Settings for proxy credentials, MCP, storage and documentation; clicking its label opens extension settings.

{
  "minecraftWorkbench.language": "en",
  "minecraftWorkbench.minMemory": 0,
  "minecraftWorkbench.maxMemory": 0,
  "minecraftWorkbench.memoryPercentage": 25,
  "minecraftWorkbench.sources": {
    "manifest": "official",
    "assets": "bmclapi",
    "libraries": "bmclapi"
  }
}

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/query. BMCLAPI applies only to supported endpoints; failed mirrors fall back to the original source. Authentication always uses official endpoints.
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.
Reuse and speed: verified files share a content-addressed cache across instances. New instances reuse a complete matching runtime and pinned loader in the same shared directory; changing loaders reuses the base client and assets and adds the required loader files. 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.
Download recovery: .part files and HTTP Range validators allow resuming when the server supports it. A server ignoring ranges restarts the file. Published Minecraft/Modrinth hashes and JDK SHA-256 checks verify downloads.
Directories: storage, game, server and project locations are configurable. New instance metadata follows Prism/MultiMC; .workbench holds only auxiliary content indexes, history and backups. Older instances may keep their existing .runtime directory.
Process downloads: these settings cover extension-managed downloads. Gradle and server bootstrappers/installers can make additional downloads under their own configuration.
Diagnostics: More → Tasks shows background work and Gradle tasks, with cancellation and retry. More → Output offers Workbench logs and the current mode’s game log, server output or Gradle terminal. Workbench logs include stages, elapsed time and nested errors; set the output channel log level to Debug for download/cache diagnostics. Request diagnostics omit headers, bodies and URL query strings. More → Export launcher logs… (also in Tools) lets you choose Sanitized (default) or Original, then saves a ZIP with an English environment/configuration report and detailed launcher traces, including launch commands, Java selection, downloads, PIDs and exits. Sanitized exports mask home directories and player identifiers; original exports retain them. Both exclude sign-in tokens and passwords and do not read SecretStorage. Collection includes debug traces regardless of the output channel display level. Original game/tool output keeps its language; VS Code task terminal text is unavailable through the stable API. Use Open Game Log for the full game log. Extension output redacts authentication tokens and proxy credentials. Review external game/mod logs before sharing them.

Development and validation

npm ci
npm test
npm run format:check
npm run legal -- --check
npm run compile
npm run test:host
npm run test:compat
npm run package

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

Host 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 uses the bundled application ID or a configured one and needs a real account, so it is not exercised automatically. Game launch, Gradle builds and installation/start/stop of Paper, Fabric, Quilt, Forge and NeoForge 1.21.4 servers have been checked on macOS Apple Silicon; other platforms and every historical game/loader combination have not been manually verified.

npm run test:compat checks extension activation, consent, mode switching and MCP against the minimum supported VS Code in an isolated profile.

Screenshots show the running extension in VS Code with sample instances and live Modrinth metadata. Project icons and descriptions belong to their respective authors.

Feedback and contributions

Bug reports, feature requests, translations and pull requests are welcome.

Bugs: search existing issues first, then open an issue. 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.
Feature requests: describe the use case and the workflow you would like to improve in an issue. Screenshots or small examples help explain UI suggestions.
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.

Remove 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; third-party content retains its own license.

License and acknowledgements

Built with the VS Code API, XMCL, Modrinth API, and official Fabric, Forge and NeoForge templates. Independent of Mojang, Microsoft, Modrinth and the loader projects. Game files, accounts and downloaded content retain their respective terms and licenses.

简体中文

Java 设置、任务、输出分别放在更多。模组项目只出现在开发模式，各模式使用对应的管理页面。可通过 minecraftWorkbench.showRuntimeViews 单独显示 Java 和任务分栏。插件设置页跟随插件语言，也保留 VS Code 原生设置入口。

在 VS Code 中启动 Minecraft Java 版、管理实例并开发模组。使用原生侧栏、命令、设置、任务和输出窗口；编辑器页面适配深色、浅色与高对比主题。默认跟随 VS Code 语言，也可单独手动选择英文或简体中文。

本分支说明： 本仓库由 ZIT Studio 维护，作为 BlockIDE 使用的分支，派生自 Lopleec/VSCode-minecraft-workbench。启动器功能来自上游，差异见本分支的更改。

本分支的更改

本分支保留上游功能，并增加 BlockIDE 集成：

内置 Microsoft Client ID。 默认提供 Microsoft 公共客户端 Client ID，无需先自行填写即可发起正版登录。可在 工具 → 账户 或 minecraftWorkbench.microsoftClientId 中替换；清空后需填写应用 ID 才能使用正版登录，离线账户不受影响。
BlockIDE 构建集成。 构建脚本为 .esbuild.mts，基于脚本所在目录解析入口和输出，分别生成扩展宿主产物 dist/extension.js 与 Webview 产物 dist/workbench.js，供 BlockIDE 作为内置扩展使用。
许可声明。 LICENSE 及内置依赖声明在上游 Lopleec 版权基础上补充 ZIT Studio。

其余启动器、服务端、模组项目与 MCP 功能与上游一致并随上游更新。独立 VSIX 由上游项目发布。

安装与开始使用

需要桌面版 VS Code 1.96+，仅支持 Minecraft Java 版。游戏所需 Java 可在插件中检测、手动添加或下载；开发模组需要 JDK。首次下载需要网络，完整安装后可使用离线账户启动，无需重新获取版本清单。

打开最新 Release。
在 Assets 中下载 minecraft-workbench-<版本号>.vsix。
在 VS Code 中执行 扩展：从 VSIX 安装…，选择下载的文件。
按提示重新加载 VS Code，然后打开活动栏中的 Minecraft。

下载和启动进程需要受信任的工作区。开发构建可从成功的 CI 运行中下载 Artifacts → minecraft-workbench-vsix，解压后安装其中的 VSIX。

安装 VSIX 不需要额外安装 Node.js，扩展使用 VS Code 自带的运行时。从源码构建、打包需要 Node.js 22+，这是打包工具链的要求：

git clone https://github.com/zitzhen/VSCode-minecraft-workbench.git
cd VSCode-minecraft-workbench
npm ci
npm run package

生成的 .vsix 按上面的步骤安装。

Publisher 为 Lopleec，扩展 ID 为 Lopleec.minecraft-workbench。从旧的 minecraft-workbench.minecraft-workbench 开发包升级时，请先卸载旧包。扩展会检测并复用原有默认存储；Microsoft 账户需要重新登录，因为 SecretStorage 按扩展 ID 隔离。 SSH、WSL、容器中的文件和进程位于扩展宿主机器；在远程机器运行游戏需要图形环境。

插件更新

GitHub / 手动 VSIX 安装可使用更多 → 检查插件更新。点击后才联网检查；有新的稳定版本时，可打开下载链接、更新说明，或在本地桌面窗口选择下载并安装。安装前校验发布的 SHA-256、扩展标识、版本与 VS Code 要求。重新加载仍需另行点击，游戏或服务端运行时不会执行。

关闭 minecraftWorkbench.updates.enabled 可隐藏入口并禁用、取消检查。没有启动检查、定时检查或静默安装。Marketplace 安装继续由 VS Code 管理更新。VS Code 没有公开的安装来源 API，因此通过本地安装记录识别；来源不明或远程窗口提供手动下载链接。VSIX 记录只能识别手动安装，不能证明下载网站。

首次使用与协议

首次打开会显示 协议与关于。阅读链接中的 Minecraft EULA 与插件的用户协议和声明，勾选两项后选择 同意并继续。两项默认均未勾选；选择 暂不使用 会关闭页面，插件操作保持不可用。

未同意时仅开放协议阅读、语言选择、确认与关闭，其余插件命令和操作均锁定；侧栏“语言”仍可修改插件整体的语言。

协议页默认跟随插件语言；手动选择只改变协议页，不修改插件、侧栏或 VS Code 的语言设置。插件整体默认跟随 VS Code。

仅将提示版本、确认时间和两项选择保存在本地 VS Code 配置中。插件提示更新后需重新确认；此版本号不代表 Mojang EULA 版本。之后可通过侧栏或命令面板的 协议与关于 再次查看。此确认不为 MIT 增加限制，也不授予 Minecraft 游戏许可。

启动模式

打开 实例 → 新建实例，填写名称，选择游戏版本、加载器和父目录。
在 工具 → 账户 添加离线账户，或按下文配置 Microsoft 登录。
在 更多 → Java 设置 或 工具 → Java 检测、添加 Java 或下载 Eclipse Temurin JDK。
选择 安装 / 修复，完成后启动。也可先保存实例，稍后安装。

版本列表包含 Mojang 清单中的正式版、快照与预发布版、愚人节版本、旧 Beta 和旧 Alpha。支持对应游戏版本可用的 Vanilla、Fabric、Quilt、Forge、NeoForge，以及 Loader 测试版本。创建后可以更改游戏版本、更新或重装 Loader，失败后可修复重试。

功能	支持内容
实例	独立游戏目录、版本切换、修复、复制（可选存档）、移动目录、上次启动与游戏时长
启动	独立账户与 Java、内存、GC、JVM / 游戏参数、窗口尺寸、全屏、自动加入服务器
内容	Modrinth 模组、整合包、资源包、光影；导入本地 JAR/ZIP；启用、禁用、删除、更新
存档	完整 `saves` 备份与恢复、可选启动前备份、保留数量
下载	进度、取消、重试、断点续传、哈希校验、镜像与代理
账户与 Java	多离线 / Microsoft 账户切换、本地 Java 检测、Temurin 下载

修复实例

选择实例，在设置页点击 安装 / 修复，或执行 Minecraft Workbench：安装 / 修复实例。Vanilla、Fabric、Quilt、Forge、NeoForge 的受支持版本，以及从官方/HMCL/PCL、Prism/MultiMC、Modrinth 导入的实例，都使用同一套修复流程。

修复会按可用元数据校验客户端、依赖库、资源索引、资源和日志配置，补齐缺失、损坏文件，必要时重新生成 Loader 输出；有效文件直接复用本地文件或缓存。保持已安装的 Loader 版本，不执行升级。解压后的本地库按实例重建，存档与配置保留；具有下载或来源记录的文件会校验、恢复，其余本地模组、资源包和光影保留。

导入实例保留可读的自定义版本配置。缺失的官方父版本配置可以重新下载，已知 Loader 配置可以重建；替换前的配置备份位于 <运行目录>/.workbench/profile-backups/。无法识别且没有可恢复元数据的自定义配置，需要从原启动器或备份恢复。没有来源和元数据的文件无法凭空重建。

实例安装中、启动准备中均可点击停止，任务通知也提供取消。输出显示 Java 选择、账户准备、文件校验、本地库解压和进程启动阶段。共享运行目录的安装任务排队执行，取消等待任务不会中断其他修复。

内容浏览与依赖

从 内容 → 浏览内容 打开页面。发现页默认按下载量展示项目图标、简介和下载数，也可搜索或按相关度、关注数、更新与发布时间排序。选择实例后，可按游戏版本和 Loader 筛选兼容内容。

版本支持游戏版本、Loader 和发布类型筛选；查看全部版本 会显示不兼容版本，但不能将它们安装进当前实例。选定版本后先查看依赖计划，再安装。必需前置递归解析，可选依赖可单独勾选。

Fabric / Quilt 会读取 fabric.mod.json、内嵌模块、版本范围和声明的不兼容项；Forge / NeoForge 使用 Modrinth 声明及游戏、Loader 兼容性信息。冲突检查可发现声明的依赖问题、重复 Fabric ID、损坏文件，不能预测所有运行时或 Mixin 冲突。

已安装 页面支持筛选、导入本地文件、启用、禁用、删除和更新。更新保留禁用状态，旧文件存放在 .workbench/history。光影包需配合 Iris、Oculus 等兼容模组。

可从 实例 → 导入整合包 或 已安装 → 导入整合包… 导入本地 .mrpack，也可从 Modrinth 安装，新建实例并应用公共及客户端覆盖文件，跳过仅服务端和客户端可选文件。导出包含已启用内容与配置：已识别文件使用下载引用，本地文件作为覆盖文件。排除存档、日志、服务器列表和账户元数据。同时支持 CurseForge 导出的 ZIP（manifest.json 与覆盖文件）。在线功能关闭时使用包内文件或选择本地 JAR/ZIP；只有引用的清单不包含实际模组，离线导入无法校验 CurseForge 文件 ID。

在 发现 → 模组 的列表行直接点击安装，自动匹配版本并安装必需前置。批量安装可点击工具栏的 批量安装…，粘贴 Modrinth 链接或 ID，也可点击 多选安装 后勾选项目，点击 安装所选；默认隐藏复选框，退出多选会清空选择。自动匹配当前实例的游戏版本和 Loader，优先正式版；确认前显示必需依赖与冲突，可排除没有兼容版本的项目。多个模组共用的前置只安装一次。已安装 → 批量管理 支持选择筛选结果，批量启用、禁用和删除文件。内容工具栏可切换 自动布局、左右分栏、单栏，也可设置 minecraftWorkbench.contentLayout。

CurseForge 下载（Beta）

默认可手动导入本地 CurseForge ZIP。CurseForge 元数据与自动下载默认关闭，需在设置中开启 minecraftWorkbench.curseforge.enabled；然后执行 Minecraft Workbench：配置 CurseForge API 密钥，或打开 工作台 → 设置 → CurseForge API 密钥。密钥保存在 SecretStorage，仅发送至官方 API/CDN，不写入设置、URL 或导出的整合包记录。参见 API 密钥申请与 CDN 认证说明。

Beta 按清单锁定的项目、文件 ID 下载并校验哈希。作者禁止第三方下载的文件，需从官方页面手动下载，再校验原始哈希。关闭 Beta 会取消进行中的请求；本地导入、使用本地文件修复仍可使用，无需 API 请求或密钥。不支持 CurseForge 分享码导入。

Modrinth / CurseForge 整合包保留可管理文件的下载或本地来源记录，供 安装 / 修复 使用；禁用状态保持不变，用户更新过的模组保留新版本，通过内容管理删除的文件不再恢复。仅有本地来源的文件需要保留原 ZIP 或所选源文件，才能在文件缺失时补回。

内存、语言与实例设置

内存在创建后的实例设置或全局设置中调整。默认最小、最大内存为 0（自动）：最大值取系统内存的 25%，向下取整到 128 MB，上限 8 GiB；最小值随之调整，通常为 256–1024 MB。可修改全局百分比，或取消 使用全局内存设置，为实例单独填写。手动值优先。

通过侧栏语言或命令面板 切换语言 即时切换；也可在插件设置中选择语言。语言可独立于 VS Code 设置。

修改内容、版本或恢复存档前需停止实例。恢复前自动备份当前存档。删除实例会将整个游戏目录移至系统废纸篓（系统支持时）。

账户与 Microsoft 登录

本分支内置默认的 Microsoft Client ID。 可直接使用，也可在 工具 → 账户 或 minecraftWorkbench.microsoftClientId 中替换为自己的公共客户端应用 ID；清空后仅能使用离线账户。离线身份无法通过要求 Microsoft / Minecraft 验证的服务器认证。

自定义应用 ID 必须支持设备代码流程、个人 Microsoft 账户、Xbox 登录并获得 Minecraft Services 访问许可；仅创建应用 ID 不保证获得 Minecraft Services 许可。不需要也不会收集客户端密钥。

通过 Microsoft 设备登录页面授权。刷新令牌和 Minecraft 访问令牌存于 VS Code SecretStorage，到期前及启动前自动刷新；刷新失败需重新登录。移除账户会删除保存的凭据，账户名和 UUID 作为本地元数据保存。插件不收集遥测。

开服模式

在模式选择器中选择开服，然后打开 服务端 → 新建服务端。选择服务端类型、Minecraft / 软件版本和构建版本。创建并启动 会下载服务端、检测或下载所需 JDK，然后启动；也可选择仅安装或仅创建。首次启动游戏服务端时需要确认 Minecraft EULA。

支持下载 Vanilla、Paper、Purpur、Folia、Fabric、Quilt、Forge、NeoForge、Velocity。Spigot、Bukkit、自定义 JAR 使用本地提供的可执行服务端 JAR。版本以各项目发布列表为准，并非每个历史 Minecraft 版本都提供独立服务端；实验构建需明确选择。

通过 服务端 → 导入服务端 可原地管理已有目录，识别可执行 JAR 和 Forge / NeoForge 参数文件，不运行启动脚本、不重复安装，保留已有存档、配置和插件。导入的 eula.txt 不代替手动确认，首次启动前需在 控制台与设置 → 协议与许可 勾选确认 EULA，AI 工具不能代为确认。

控制台与设置 包含输出、指令、正常停止和重启、Java 与内存、服务端属性、版本更换、修复和存档备份。编辑内容或恢复存档前需要停服。正常停服会发送保存与关闭指令；强制停止需确认。从列表移除服务端时会保留文件。

侧栏内容、发现与 已安装 使用当前服务端的兼容条件。Paper / Purpur 可安装兼容的 Bukkit、Spigot、Paper 插件；Folia 仅接受明确声明支持 Folia 的版本；Spigot / Bukkit 使用对应插件平台；Velocity 筛选其对应插件。Fabric、Quilt、Forge、NeoForge 使用服务端模组。版本、简介、图标、前置预览、更新、启用、禁用和删除与客户端使用同一套页面；拒绝仅客户端项目，也可导入本地 JAR。自定义 JAR 不会自动推断插件或模组平台。

新游戏服务端默认绑定 127.0.0.1。局域网访问可在 设置 → 网络 → 绑定地址 中改为 0.0.0.0。防火墙、路由器端口转发和公网托管需另行配置。Velocity 属于代理端，可通过 打开配置文件 编辑 velocity.toml，设置后端服务端。

AI 与 MCP

MCP 默认关闭。点击 工作台 → 设置 → 注册 MCP，或启用 minecraftWorkbench.mcp.enabled，VS Code 1.101 及以上可在 MCP 提供程序和聊天工具选择器中启用 Minecraft Workbench；1.96–1.100 使用 设置 → 复制 MCP 连接 配置支持 MCP 的客户端，工具和访问控制保持一致。取消注册 MCP 会移除服务定义并关闭监听。

工具覆盖实例创建与启动、游戏及 Loader 版本、Modrinth 内容与前置、账户、Java、任务、备份、Gradle 项目、服务端管理和扩展设置。workbench_state 可获取当前列表。需要文件选择或确认的操作仍使用 VS Code 原生界面。AI 工具不能代替用户同意首次使用协议；服务端 EULA 也需要交互确认。

注册一次即可调用三个模式的工具，切换界面模式不需要重新连接，也不会隐藏其他模式的工具。先用 workbench_state 获取 ID，再操作对应条目：

模式	MCP 功能
启动	实例创建、导入、设置、修复与启动；内容、账户和存档备份
开发	`project_import`、`project_templates`、`project_create`、`project_configure`、`project_status`；`project_action` 可构建、运行、调试、附加调试器、停止任务和打开产物
开服	服务端版本、创建与导入、本地 JAR 和插件／模组导入、设置、启停、控制台指令、日志与存档备份

内容操作使用 instanceId 或 serverId，两者不能同时传入；明确指定的 ID 优先于当前界面模式，服务端会默认匹配对应的模组／插件平台。在开发模式中操作内容需明确指定目标。Java、任务和插件设置由三个模式共用。项目导入保留原文件，仅 open=true 时打开窗口。

其他 MCP 客户端可使用 复制 MCP 连接，按客户端格式填入复制的 Streamable HTTP 配置。配置包含本地 URL 与授权请求头，仅在当前扩展宿主会话中有效；请勿公开请求头。接口只监听 127.0.0.1 并检查授权。远程工作区中，接口运行在扩展宿主机器。工具结果可能包含本地路径、项目信息和控制台日志，并适用所连接 AI 客户端的数据政策；工具不会返回登录令牌。

开发模式

在侧栏或状态栏切换到 开发模式，打开项目。

选择 Fabric / Forge / NeoForge 和官方模板或 MDK 版本。
填写模组名称、ID、Java 包名和目录。包名建议使用通用的 com.example.<mod_id>，可自行修改。
创建后自动打开项目，也可关闭该选项；支持导入包含 Gradle wrapper 的已有项目。
项目操作支持构建、清理、启动客户端、生成源码 / IDE 文件和查看构建产物。
调试时先选择 启动客户端并等待调试，待 Gradle 监听端口后 附加调试器。按提示安装 Debugger for Java，默认端口 5005。

Gradle 通过项目 wrapper 在 VS Code Tasks 中运行，首次会下载 Gradle 与依赖。模板提供对应的游戏、Loader 和 Gradle 版本，部分历史版本没有维护中的模板。生成的是模组项目，并非反编译后的独立游戏客户端。插件代理用于插件管理的下载；Gradle 的仓库与代理遵循项目及 Gradle 配置。

展开 项目设置 可指定此项目的 Java、Gradle 参数和调试端口；Java 留空、端口填 0 使用插件默认值，项目设置优先。缺少 JDK 时会自动准备。停止 Gradle 任务 可停止正在构建或运行的测试客户端，重新读取项目元数据 会读取 gradle.properties 的变化；再次导入同一项目会更新元数据并保留原有设置。

网络、目录与诊断

编辑器使用工具菜单进入账户、Java、任务及设置，实例选择只出现在需要目标的页面。工作台保留模式、语言和设置；更多默认收起，包含 Java、任务、输出和协议。展开设置可管理代理凭据、MCP、存储目录或查看文档；点击设置文字打开插件设置页，其中保留 VS Code 原生设置入口。MCP 默认关闭。分类保留 VS Code 原生分栏、分隔线和滚动；在 工作台 → … → 显示侧栏分类 中可直接找回被隐藏或移到下方的分类。

全局选项位于 Minecraft Workbench：设置 页面，也可从该页打开 VS Code 原生设置。

{
  "minecraftWorkbench.language": "zh-cn",
  "minecraftWorkbench.minMemory": 0,
  "minecraftWorkbench.maxMemory": 0,
  "minecraftWorkbench.memoryPercentage": 25,
  "minecraftWorkbench.sources": {
    "manifest": "official",
    "assets": "bmclapi",
    "libraries": "bmclapi"
  }
}

下载源： 可按 manifest、client、server、assets、libraries、loader、modrinth、java、project 设置 official、bmclapi 或 HTTPS 基地址。自定义地址保留原路径和查询参数；BMCLAPI 仅用于支持的端点。镜像失败回退原始地址，认证始终走官方端点。
代理： 支持 HTTP、HTTPS、SOCKS5、SOCKS5h；SOCKS5 本地解析域名，SOCKS5h 由代理解析。留空时沿用 VS Code http.proxy。使用 工作台 → 设置 → 代理凭据 将凭据存入 SecretStorage。修改网络、存储配置后需重载窗口。
断点与校验： 保留 .part，在服务器支持时使用 HTTP Range 和校验器续传；服务器忽略范围则重新下载。校验 Minecraft / Modrinth 公布的哈希及 JDK SHA-256。
目录： 存储、游戏、服务端和项目目录可配置。新实例采用 Prism/MultiMC 格式；.workbench 只保存辅助索引、历史和备份。旧实例保留原有 .runtime。
日志： 更多 → 任务 管理后台操作和 Gradle 任务；更多 → 输出 提供工作台日志及当前模式的游戏日志、服务端输出或 Gradle 终端。日志包含阶段、耗时与错误原因链；Debug 级别提供下载和缓存诊断，请求诊断不记录认证头、请求体或 URL 查询参数。更多 → 导出启动器日志…（编辑器中也可从工具进入）先选择 脱敏版（默认） 或 原始版，再保存 ZIP，包含英文环境和配置报告、启动命令、Java 选择、下载过程、PID 和退出信息。脱敏版隐藏用户目录及玩家身份信息，原始版保留这些信息；两者均排除登录令牌和密码，不读取 SecretStorage。诊断文件始终收集 Debug 细节，不依赖输出窗口的显示级别；游戏及外部工具原始输出保留原语言。VS Code 稳定 API 无法读取任务终端全文。分享外部日志前仍需检查内容。

下载复用与并发

带校验和的文件在实例间使用共享缓存，包括客户端、库、资源、服务端、JDK 和 Modrinth 文件。新实例会复用同一共享目录中已完整安装的对应核心与固定版本 Loader；切换 Loader 时保留基础客户端和资源，只补对应 Loader 所需文件。旧实例中的文件也会在校验后纳入缓存；相同版本只补缺失或不同的资源，实例文件保持独立副本。

至少 16 MiB 的文件默认使用 4 个 HTTP Range 连接、每段 8 MiB；全局并发上限默认为 6。重试保留已完成分段，不支持分段的源自动回退单连接。可配置 sharedDownloadCache、downloadConnectionsPerFile、downloadChunkSize、downloadConcurrency。设置作用于插件管理的下载；Gradle、服务端引导程序和安装器可能另行下载其依赖。

开发与验证

npm ci
npm test
npm run format:check
npm run legal -- --check
npm run compile
npm run test:host
npm run test:compat
npm run package

按 F5 打开扩展开发宿主。单元测试覆盖路径安全、状态保存及失败恢复、账户、续传、哈希、依赖、备份和项目定制。CI 在 Linux、Windows 和 macOS 检查格式、测试、编译和打包。

宿主测试需要网络与本地或可下载的 VS Code。VSCODE_EXECUTABLE 可指定本地程序，MW_LIVE_INSTALL=1 会额外下载安装 Fabric 测试实例。Microsoft 登录使用内置或自定义应用 ID 及真实账户，不自动测试。游戏启动和 Gradle 构建，以及 Paper、Fabric、Quilt、Forge、NeoForge 1.21.4 服务端的安装、启动和停服，已在 macOS Apple Silicon 验证；其他平台及所有历史游戏 / Loader 组合尚未逐一人工验证。

npm run test:compat 会在隔离配置中使用最低支持的 VS Code，检查激活、协议保护、模式切换和 MCP。

截图来自 VS Code 中运行的插件，使用示例实例和实时 Modrinth 元数据。项目图标、简介属于各自作者。

反馈与贡献

欢迎提交问题、功能建议、翻译改进和 Pull Request。

问题反馈： 请先搜索已有 Issue，再创建 Issue。提供复现步骤、预期与实际表现、插件及 VS Code 版本、系统与架构。游戏相关问题请附上 Minecraft、Loader、Java 版本、相关模组和简短日志。
功能建议： 在 Issue 中说明使用场景和希望改善的操作流程。界面建议可附截图或小示例。
提交 PR： Fork 仓库并创建分支，每个 PR 聚焦一项改动，说明问题、修改内容和验证方式。较大改动建议先通过 Issue 讨论。遵循现有代码风格，修改界面文案或文档时同步更新中英文，界面改动附上截图。提交 Pull Request 前运行上文列出的相关检查。

分享日志和截图前，请移除令牌、代理凭据、账户信息和个人路径。源码贡献中不要包含下载的游戏文件、存档、本地实例数据或生成的 VSIX。贡献采用项目的 MIT License，第三方内容保留各自许可。

许可与致谢

使用 VS Code API、XMCL、Modrinth API，以及 Fabric、Forge、NeoForge 官方模板。本项目独立于 Mojang、Microsoft、Modrinth 和各 Loader 项目。游戏文件、账户与下载内容仍适用各自条款和许可。

界面示例

现有实例与存储

实例卡片和设置页的 打开实例目录 可直接打开游戏文件。实例设置 → 移动实例 搬迁整个实例，包含世界、模组和配置，支持跨磁盘移动；实例外部的共享运行库保持原位。原地管理的实例需先复制再移动。存档备份 → 打开世界存档目录 可直接打开 saves。

新建实例统一使用 Prism / MultiMC 格式：以实例名称建立目录，其中包含 instance.cfg、mmc-pack.json 和 .minecraft 游戏目录。世界存档仍是 saves/世界名称/ 下的原生 Java 版存档。版本文件、运行库和资源使用系统 Minecraft 目录，也可通过 minecraftWorkbench.gameDirectory 更改。minecraftWorkbench.instanceDirectory 可单独指定实例父目录，包括现有的 PrismLauncher instances 目录。旧版工作台实例继续兼容。

在 实例 → 导入实例 中扫描 Minecraft/HMCL/PCL 目录、Prism/MultiMC 实例目录、Modrinth 档案目录或 ZIP 导出文件，预览会显示识别出的 Minecraft 和 Loader 版本。原地管理保留原目录，与原启动器共用文件，移除登记时保留游戏文件；复制导入创建独立的 Prism/MultiMC 实例，保留模组、配置和世界存档。不会导入原启动器的执行钩子或账户数据库。标准 Minecraft / HMCL / PCL 实例的运行文件完整时会直接识别为已安装，缺失资源时才补齐。

导出实例生成 Prism/MultiMC ZIP，可选包含世界存档；导入整合包 / 导出 .mrpack 使用 Modrinth 格式。新版 Modrinth App 若未保留 profile.json，请先导出 .mrpack。旧式 Jar 模组、无法识别的 MultiMC 组件会明确提示，不会静默忽略。支持原地管理标准 HMCL 补丁配置，保留原始元数据。ZIP 超过 512 MB 时，请先解压或直接复制实例目录。

存档备份 → 导入 / 导出世界存档支持原生 Java 版世界目录和 ZIP，可使用其他启动器中的存档。同名世界另建编号副本。基岩版 .mcworld 需先转换格式。

游戏语言首次跟随扩展，扩展默认跟随 VS Code。自动模式保留玩家在游戏中选择的语言；可在实例设置或 minecraftWorkbench.gameLanguage 中覆盖，取值为 auto、preserve 或 en_us、zh_cn 等 Minecraft 语言代码。

账户 → 外置登录支持 authlib-injector。可选择 LittleSkin 预设，或填写自定义 HTTPS Yggdrasil API 地址，在 VS Code 中输入凭据并选择角色。支持 ALI 地址识别；令牌保存在 SecretStorage，不保存密码。启动前校验、刷新令牌，需要时下载并进行 SHA-256 校验的 authlib-injector。外置账户只能用于配置了对应认证服务的服务器。

输入凭据前，需在原生风险提示中核对识别后的完整认证 API 地址并确认。用户名、密码会发送给服务商，由其签发令牌；请使用独立密码，切勿填写 Microsoft 密码。HTTPS 不代表服务商可信。移除账户只删除本地凭据，如需撤销访问，请前往服务商处理。界面不预选服务商。第三方服务与许可列明服务条款、隐私链接及单独下载组件的许可。

陶瓦联机（Beta）

此可选功能默认关闭。在设置中开启 minecraftWorkbench.terracotta.enabled 后，从 更多 → 陶瓦联机（Beta） 进入。下载和运行组件前需阅读上游许可及联机须知，分别勾选确认；须知语言可以单独切换，不更改扩展语言。

点击 下载安装 获取并校验官方组件，或选择已有的官方可执行文件；页面也提供 官方下载 链接。下载固定支持版本并校验官方 SHA-256；macOS 需先打开官方安装包，配置其后台组件，再连接。
连接组件。房主将 Minecraft 世界开放到局域网后点击创建房间；访客填写陶瓦房间码并加入房间。
访客可复制游戏地址，或直接启动所选实例进入房间；临时地址不会覆盖实例原有的服务器设置。
结束后退出房间。关闭设置或撤回确认会断开本扩展创建的连接。可通过 minecraftWorkbench.terracotta.publicNodes 指定额外公共节点。

Terracotta / 陶瓦联机是 Burning_TNT 及贡献者的独立项目，采用附带上游例外的 AGPL-3.0-or-later。插件通过本地 HTTP 接口调用未修改的官方程序，不将它打包进扩展。当前 Beta 面向陶瓦 0.4 接口及 Java 版局域网世界；穿透和中继可用性取决于各方网络与外部服务。请仅向希望加入的玩家分享房间码。

Java 优先级为：实例单独设置 → 全局默认 → 自动检测 / 下载。实例设置可留空；更改其他字段不会清除已有的 Java 配置。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.vscode		.vscode
docs/images		docs/images
licenses		licenses
media		media
scripts		scripts
src		src
test		test
.esbuild.mts		.esbuild.mts
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierrc.json		.prettierrc.json
.vscodeignore		.vscodeignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
TERMS.md		TERMS.md
THIRD_PARTY_LICENSES.txt		THIRD_PARTY_LICENSES.txt
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
package-lock.json		package-lock.json
package.json		package.json
package.nls.json		package.nls.json
package.nls.zh-cn.json		package.nls.zh-cn.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation