• 桌面应用
  • 游戏开发

【免费下载链接】mcaselector

A tool to select chunks from Minecraft worlds for deletion or export.

项目地址： https://gitcode.com/gh_mirrors/mc/mcaselector
点击查看 免费下载

MCA Selector（mcaselector）是一款运行于 Minecraft Java Edition 存档之外的独立区块管理工具，核心用途是从世界存档中按选择或按过滤器导出/删除指定的区块（Chunk）与区域（Region）。本文将基于本仓库的 README 与源码实现，完整介绍它的获取安装方式、受支持的 Minecraft 版本范围、区块与 MCA 文件格式原理，以及 GUI 选择、过滤器查询、无头 CLI、NBT 字段修改等核心能力，读完即可安全地用它完成区块重置、区域清理、区块搬迁等实操任务。

项目定位：存档外部的区块管理工具

按 README 的定义，MCA Selector 是 "An external tool to export or delete selected chunks and regions from a world save of Minecraft Java Edition"——它不修改 Minecraft 本体，也不作为模组加载，而是作为独立程序直接读写存档目录中的 MCA 区域文件。应用场景包括：

  • 重置出生点附近区块、让地形按新版本世界生成规则重新生成；
  • 删除特定范围内的区块以清理陈旧建筑或错误生成；
  • 将某个区域的区块导出成独立的世界片段，或从一个世界导入到另一个世界；
  • 对存档进行按条件的批量区块处理（例如删除所有实体数量超过阈值的区块）。

从源码的启动流程 Main.java 可以看到它的运行方式：先初始化日志目录，通过 VersionHandler.java 装载按 Data Version 分档的版本实现，然后处理命令行参数；若存在 JavaFX 运行时则进入 GUI 窗口，否则给出 "Please install JavaFX" 提示。这意味着工具本身是图形界面 + 命令行双形态的，后面会分别展开。

获取与安装：下载渠道与运行前提

⚠️ 安全提示（README 原文强调）：唯一官方、安全的下载来源是项目官方 GitHub Releases 页面。仓库的 installer 目录只包含各平台安装包制作所需的资源文件（如 mcaselector.desktop、inno.iss），而非可直接运行的成品。

官方发布的分发格式（对应当前 README 中标注的版本）：

平台格式
Windows.exe 安装程序（Setup）
macOS.dmg，分别提供 arm64（Apple Silicon）与 x64（Intel）两个架构包
Linux.deb 与 .rpm，同样区分 arm64 与 x64
全平台通用Universal jar（mcaselector-<version>.jar），依赖本机 Java 运行

如果你希望从源码自行构建，可以用 git clone 获取本仓库（gitcode 镜像地址：https://gitcode.com/gh_mirrors/mc/mcaselector），然后通过仓库根目录的 gradlew / gradlew.bat 包装脚本执行 Gradle 构建。

运行前提：作为 Java 应用，运行 Universal jar 需要本机安装合适的 Java 运行时，且 GUI 模式额外依赖 JavaFX（Main.java 中显式检测，缺失时会弹出错误对话框说明）。

受支持的 Minecraft 版本范围

README 明确给出了当前支持的版本与对应 Data Version（存档根标签中的 DataVersion 整型值）对照表：

Minecraft VersionData Version
1.2.1 - 1.12.2None - 1343
1.13 - 1.13.21444 - 1631
1.14 - 1.14.41901 - 1976
1.15 - 1.15.22200 - 2230
1.16 - 1.16.52566 - 2586
1.17 - 1.17.12724 - 2730
1.18 - 1.18.22825 - 2975
1.19 - 1.19.43105 - 3337
1.20 - 1.20.63463 - 3839
1.21 - 1.21.113953 - 4671
26.1 - 26.3+4764 - 5023+

快照（Snapshot）版本警告：即使某快照版本出现在上表中，也不保证其生成的存档一定能正常工作；该范围只代表面向下一个正式版 Minecraft 的开发状态，历史版本的旧快照不受官方支持。从源码看，版本支持正是以 Data Version 为索引实现的：VersionHandler.java 通过 floorEntry(dataVersion) 取出"不大于该数据版本"的最近实现，并在 src/main/java/net/querz/mcaselector/version 下按 java_1_9、java_1_13 直到 java_26 分目录维护了不同版本的区块解析与颜色映射逻辑（如 ChunkFilter_1_21_5_RC2.java、ColorMapping_25w32a.java）。

区块、区域与 MCA 文件格式基础

理解工具行为之前，需要先建立 Minecraft 存档的坐标体系（源码中由 Point2i 等类型承载）：

  • 区块（Chunk）：16×16 方块的水平区域，是游戏加载与存储的基本单位；
  • 区域（Region）：32×32 个区块（共 1024 个）组成的正方形，对应存档 region 目录下的一个 r.<x>.<z>.mca 文件。文件名中的 x/z 即区域坐标，FileHelper.java 通过正则 r.<regionX>.<regionZ>.mca 解析。

一个 "Region" 在 MCA Selector 中实际由三类文件组成，这一点在 Region.java 中体现得很明确：

文件类型目录内容
RegionMCAFileregion/常规区块数据（方块、生物群系、高度图等）
PoiMCAFilepoi/兴趣点数据（床、工作站点等，1.14+）
EntitiesMCAFileentities/实体数据（1.18+ 拆分存储）

因此对区块的删除、导出、导入操作，Region.java 的 deleteChunks / mergeInto 等方法都会同时作用于三类文件，保证存档一致。

MCA 文件的物理格式（MCAFile.java）是理解一切读写操作的基础：

  • 文件头固定 8192 字节（2 个扇区，常量见 FileHelper.java）；
  • 头部前 4096 字节为 偏移表：每个区块 4 字节，3 字节记录该区块数据起始扇区号、1 字节记录占用扇区数；
  • 随后 4096 字节为 时间戳表：每个区块 4 字节 UNIX 时间戳；
  • 区块数据按 4096 字节扇区对齐存放，读取逻辑见 MCAFile.java；
  • 区块 NBT 数据按不同的压缩方式编码，CompressionType.java 定义了 GZIP、ZLIB、UNCOMPRESSED、LZ4 以及对应的外部存储变体（_EXT，数据存于 c.x.z.mcc 文件）。

核心工作流：选择 → 删除 / 导出 / 导入

选区（Selection）与 CSV 文件

无论 GUI 拖选还是 CLI 指定，选区的落地格式都是 CSV 文件，其读写实现在 Selection.java：

  • 每行格式为 regionX;regionZ（表示整个区域被选中），或 regionX;regionZ;chunkX;chunkZ（表示该区域内某个具体区块被选中，且区块坐标必须落在该区域内，否则读取时报错）；
  • 若首行为 inverted，则整个选区是**反转（反选）**语义：不在列表中的区域/区块反而被选中，isChunkSelected 中按 (chunks == null || chunks.get(chunk)) != inverted 判定。

选区支持合并（merge）、求差（subtract）、加半径（addRadius，即向选中区块的四周扩展指定圈数）等集合运算，GUI 中框选、Ctrl 加选等交互最终都归结为这些运算。

删除与导出：源码级调用链

  • 删除：GUI/CLI 触发 ChunkFilterDeleter.java → 对每个区域文件执行 Region.deleteChunks（逐区块套用过滤器与选区判定）→ MCAFile.deleteChunks 将对应偏移、扇区、时间戳清零 → 落盘时通过 deFragment() 重写文件，若整个文件已无任何区块则直接删除空文件。
  • 导出：ChunkFilterExporter.java 按"保留匹配条件/选区的区块"（keepChunks，其余删除）的方式裁剪出结果，并写入目标世界目录；若目标位置已存在同名文件则跳过不覆盖。

导入则通过 ChunkImporter.java 配合三维偏移（x-offset / y-offset / z-offset，Y 方向限制在 -24～24）将源区块搬迁到目标世界，支持 --overwrite 覆盖与按 section 范围（--sections，如 0,1-3）的部分导入。

过滤器（Filter）系统：按条件批量选中区块

除手动框选外，MCA Selector 支持过滤器查询，让程序按 NBT 内容等条件自动判定每个区块是否命中。过滤器类型注册在 FilterType.java，主要包括：

过滤器类型匹配内容值形式
DataVersion区块 Data Version数字
InhabitedTime区块已居住时间数字
xPos / yPos / zPos区块坐标数字
Timestamp / LastUpdate文件时间戳 / NBT 最后更新时间数字
Compression区块数据压缩方式文本
Palette区块使用的方块调色板文本
Biome生物群系文本
Status区块生成状态（如 full）文本
#Entities / #ProtoEntities / #TileEntities实体 / 原型实体 / 方块实体数量数字
Structures生成的结构文本
Circle / Border以选区为基准的圆形 / 边框范围文本 / 数字
Custom自定义 NBT 路径匹配文本
PlayerLocation / PlayerSpawn玩家位置 / 出生点文件
Selection引用外部选区文件文件
ScriptGroovy 脚本（需要 --script 指定 .groovy 文件）脚本

查询语法由 FilterParser.java 解析，基本形式为 类型 比较符 值：

  • 比较符（Comparator.java）：=、!=、<、>、>=、<=、contains、!contains、intersects（比较符是否可用取决于过滤器类型，解析器会校验）；
  • 逻辑组合：过滤器之间用 AND / OR 连接（Operator.java），首个条件默认为 AND；用括号 ( ... ) 分组，用 !( ... ) 对整组取反；
  • 值：可裸写（允许字母、数字、,、-、+、: 等字符）或用双引号包裹字符串；
  • 分组组合与短路求值逻辑实现在 GroupFilter.java，并可通过 appliesToRegion 先在区域层面粗筛、避免无谓加载（Region.java 中即先做 selection.isAnyChunkInRegionSelected 预判）。

无头 CLI：命令行批处理

README 侧重 GUI 形态，但仓库自带完整的命令行支持，入口为 ParamExecutor.java，启动时若传入了参数即进入无头模式（见 Main.java）。基本用法：

java -jar mcaselector.jar --mode <mode> [其他参数]

--mode（-m）支持以下模式（ParamExecutor.java）：

模式作用
select根据过滤器查询生成选区并保存为 CSV 文件
export基于过滤器查询和/或选区导出区块到新世界目录
import将源世界的区块按偏移导入目标世界
defragment对所有区域（或选区内的区域）执行碎片整理
delete基于过滤器查询和/或选区删除区块
change修改整个世界或选区区块的 NBT 字段
cache为整个世界生成缓存图像（需 JavaFX）
image基于选区生成单张图像（需 JavaFX）

常用参数包括：

  • 世界定位：--world（目标世界根目录，自动探测 region 子目录），可用 --region / --poi / --entities 覆盖；导入模式另需 --source-world 及 --output-world 等成对参数；
  • 条件：--query（过滤器查询字符串）或 --script <file.groovy>（Groovy 脚本过滤器，二选一）；
  • 选区：--selection <file.csv>，导入时另支持 --source-selection；--radius N（向选区四周扩展 N 圈）；
  • 输出：--output（CSV/PNG 文件或目录）；
  • 导入参数：--x-offset / --y-offset / --z-offset、--overwrite、--sections <0,1-3>；
  • 修改参数：--fields "字段=值,..." 与 --force；
  • 图像参数：--render-height（默认 319）、--render-caves、--render-layer-only（二者互斥）、--render-shade / --render-water-shade / --render-height-shade、--overlay-type 等；
  • 资源控制：--process-threads 与 --write-threads（取值范围 1～128）、--debug；
  • 辅助：--help（-h）与 --version（-v）。

示例（基于 ParamExecutor.java 的参数语义）：

# 删除某个世界里所有 DataVersion 达到 1.20 标准的区块并输出选区文件
java -jar mcaselector.jar -m select -w ./world --query "DataVersion >= 3463" -o selection.csv

# 按选区文件删除区块
java -jar mcaselector.jar -m delete -w ./world -s selection.csv

# 将源世界偏移 16 个区块后导入目标世界（覆盖已存在的区块）
java -jar mcaselector.jar -m import -w ./target -source-world ./source --x-offset 16 --overwrite

# 把世界导出到 output 目录，仅保留 Biome 为 plains 的区块
java -jar mcaselector.jar -m export -w ./world --query 'Biome contains "plains"' --output-world ./output

NBT 字段修改（change 模式）

change 模式允许批量改写区块 NBT，字段类型注册在 FieldType.java，语法由 ChangeParser.java 解析：字段名=值，多个字段用逗号分隔。可用的字段包括：

字段名说明
DataVersion改写 Data Version（接受纯数字，见 DataVersionField.java）
InhabitedTime / Timestamp / LastUpdate时间相关数值
Compression区块压缩方式
Status / FixStatus区块生成状态及其修复
Biome生物群系替换
ReplaceBlocks方块替换
DeleteEntities删除实体
DeleteSections删除指定 section
FixHeightmaps修复高度图
DeleteStructureReference / FixStructureReferences结构引用处理
PreventRetrogen防止区块重新生成
ForceBlend强制混合过渡
RemoveLightingInfo移除光照信息
LightPopulated光照生成标记
Custom自定义 NBT 路径修改
ScriptGroovy 脚本（仅 headless）

其中 Status、ReplaceBlocks、DeleteSections、FixStatus 等字段标注为 clearCache（见 FieldType.java），执行后会要求清理缓存图以便重新生成。

图像、缓存与 Overlay 可视化

工具提供区块级可视化能力：

  • cache 模式为整个世界生成分层缓存图（zoom level 必须是 2 的幂，范围由 Config.java 中 MIN_SCALE/MAX_SCALE 换算得到），GUI 中缩放时按需加载；
  • image 模式把选区渲染成一张 PNG 大图，支持设置渲染高度、洞穴渲染（--render-caves）、单层渲染（--render-layer-only）与明暗着色；
  • Overlay（叠加层）可把统计数据叠加到地图上，类型注册在 OverlayType.java：InhabitedTime、Timestamp、LastUpdate、#Entities、#TileEntities、DataVersion、AverageHeight、#Blocks、Path、Script，并通过 --overlay-min-value / --overlay-max-value / --overlay-min-hue / --overlay-max-hue 控制渐变区间与色相。

配置、日志与运行建议

  • 全局配置（settings.json）由 GlobalConfig.java 维护，包含语言（默认 Locale.UK）、区块/区域网格显示、选区颜色、处理线程数（默认 max(1, min(CPU核数-2, 4))）、写入线程数（默认 max(1, min(CPU核数, 4))）、最近打开的世界与脚本等；配置文件位置按操作系统区分（Windows 走 LOCALAPPDATA，macOS 走 Library/Application Support，Linux 走 XDG_CONFIG_HOME），详见 Config.java；
  • 每个世界的独立设置（渲染高度、明暗、背景色、结构图标大小等）由 WorldConfig.java 保存为 world_settings.json，并按世界路径的 UUID 放在缓存目录下；
  • 日志默认写入系统缓存/数据目录下的 mcaselector/log，--debug 可开启 DEBUG 级别日志；
  • 所有修改类操作（删除/导入/字段修改）都会真实改写存档文件，务必先备份整个世界目录——这也是 README 开篇即给出的最核心安全建议。碎片整理（defragment）可在删除大量区块后执行，压缩文件内部分布，保持区域文件健康。
  • 桌面应用
  • 游戏开发

【免费下载链接】mcaselector

A tool to select chunks from Minecraft worlds for deletion or export.

项目地址： https://gitcode.com/gh_mirrors/mc/mcaselector
点击查看 免费下载

相关推荐

上一篇： 告别手绘神经网络：PlotNeuralNet让教学可视化效率提升10倍
下一篇： 攻克跳一跳图像识别痛点：board_x与piece_x坐标修正全指南
Logo
乐奇 Rokid 开放社区

更多推荐

镜游小导：运行在 Rokid AR 眼镜上的景区实景讲解智能体

项目以 RokidAIUI 开放智能体形态交付：页面用.ink描述，运行在眼镜端智能体运行时，直接调用系统能力。AGENTS.md身份镜游小导v1.0.0，景区 AR 实景讲解智能体；权限（Capabilities）microphonenetworkaudiogyroscope；技能（Skills）。

avatar 乐奇 Rokid 开放社区
cover

AI 智能眼镜技术文档

avatar 乐奇 Rokid 开放社区
cover

Muse首发接入Rokid

avatar 乐奇 Rokid 开放社区