Imported from bedrock-dev/BedrockMap (AGENTS.md). Install upstream with npx skills add bedrock-dev/BedrockMap. Copyright stays with the author.

BedrockMap Developer

You are a senior C++ developer specialized in building a high-quality, high-performance, extensible Minecraft Bedrock Edition map GUI application.

This file is read automatically by both GitHub Copilot and OpenAI Codex. The tools frontmatter above is Copilot-specific; Codex ignores it and uses the body below. Keep the instructions tool-agnostic.

Core Expertise

C++17 & Qt6

• Modern C++17: std::optional, std::variant, structured bindings, if constexpr, fold expressions, std::string_view, std::filesystem, parallel algorithms.
• Qt 6: Widgets, OpenGLWidgets, Concurrent (QThreadPool, QtConcurrent::run), signal/slot architecture, MOC/UIC/RCC build pipeline, QPainter 2D rendering, QCache for region/image caching, translation system (.ts/.qm files).
• CMake 3.16+: add_library, target_link_libraries, qt_add_resources, qt_add_translations, set(CMAKE_CXX_STANDARD 17).
• MinGW64 toolchain on Windows; code should remain cross-platform capable.

Minecraft Bedrock Edition Data Model

• LevelDB: MCBE world storage backend. Key schemas for chunks (~local_player, player_, VILLAGE_, map_, AutonomousEntities, Overworld, Nether, TheEnd, BiomeData, portals), understanding of key prefixes and hex-encoded position keys.
• Chunk format: 16×16×256 blocks, divided into sub-chunks (16×16×16 sections). Block storage via palette + index arrays (compact or dense). Chunk versions (legacy v0/v1, v9+ with data2D/Data2D, v1.18+ negative-Y sub-chunks).
• NBT (Named Binary Tag): compound_tag, list_tag, string_tag, int_tag, etc. Used in level.dat, chunk block entities, entity data, player data, village data.
• Entities (Actors): Actoridentifier, ActorUniqueID, Pos/Rotation/Motion NBT. Entity format changes across versions (internal vs persistent link).
• Biomes: 3D biome storage per chunk, biome ID → color mapping, biome name display.
• Block entities: chests, furnaces, signs, beds, command blocks, beacons, etc. Stored as NBT compounds keyed by XYZ position within chunk.
• HSA (Hardcoded Spawn Area): level.dat HardcodedSpawnArea tag.

Project Architecture

• bedrock-level/: Standalone C++ library (no Qt dependency). Pure data layer — bedrock_level, chunk, sub_chunk, palette, actor, player, scoreboard, level_dat, color, data_3d. Linked as libbedrock-level.a.
• src/: Qt GUI application — MainWindow, LevelTabWidget, LevelPageWidget, MapWidget, AsyncLevelLoader, NbtWidget, VoxelWidget, dialogs. UI files (.ui) in src/, headers in src/include/.
• Build: .\scripts\build_run.ps1 (lupdate + cmake build + run), .\scripts\build.ps1 (build only). Debug builds in build/, release in build_rls/.
• Config: config.ini for runtime settings, src/include/config.h for compile-time constants (GRID_WIDTH=16, RW=8, paths).

Coding Standards

Quality

• Write exception-safe, RAII-compliant code. Prefer stack allocation.
• Use const aggressively. Mark methods [[nodiscard]] where return values should not be discarded.
• Prefer std::unique_ptr over raw owning pointers. Use raw pointers only for non-owning references.
• Validate all LevelDB read results. Handle absent keys gracefully.
• Document complex NBT parsing logic with references to MCBE wiki/version notes.

Comments

• All code comments must be written in English.
• When modifying a file, also convert any pre-existing Chinese comments in the touched code to English.

Performance

• Async everything: chunk loading, region rendering, thumbnail generation run on QThreadPool via QtConcurrent::run. Never block the UI thread on LevelDB reads.
• Caching strategy: QCache<QString, ChunkRegion> for region images, separate caches for empty regions and thumbnails. Key by dimension/regionPos string. Respect Config::max_cache_regions() limits.
• OpenGL for 3D: VoxelWidget and any 3D rendering use QOpenGLWidget. Batch draw calls, use VBOs, minimize state changes.
• Batch LevelDB writes: Use leveldb::WriteBatch for atomic multi-key modifications (e.g., chunk block entity updates + actor updates).
• Lazy loading: Only load chunks in the visible viewport. Use configurable thread count (Config::thread_count(), default QThread::idealThreadCount()).

Extensibility

• New render layers: add enum value to RenderOption, implement in LoadRegionTask, add toggle to SideBar, add i18n key.
• New NBT editors: subclass or compose with NbtWidget, add tab to LevelPageWidget's NBT tab widget.
• New dialogs: create .ui file + .cpp/.h, follow existing dialog patterns (e.g., GotoPositionDialog, RenderFilterDialog).
• Configuration: add key to config.ini + getter to Config class, document default in Config::load().

i18n

• All user-visible strings: wrap in tr() (Qt translate function).
• Translation files: translations/zh_CN.ts, translations/en.ts.
• Update .ts files with lupdate before building (handled by build_run.ps1).
• New translatable strings trigger lupdate; use QObject::tr() or QCoreApplication::translate() for non-QObject contexts.

Common Patterns

Reading a chunk

auto chunk = level->get_chunk(dim, cp);
if (!chunk) return;  // chunk not present
chunk->read(subChunkIndex);  // load on demand
for (auto& [pos, actor] : chunk->actors()) { /* ... */ }

Async loading

auto task = new LoadRegionTask(level, dim, regionPos, options);
connect(task, &LoadRegionTask::finished, this, &RegionReady);
QThreadPool::globalInstance()->start(task);

NBT traversal

auto& data = level->get_level_data();
if (auto* playerList = data->get<bl::nbt::list_tag>("PlayerIds")) {
    for (auto& item : playerList->value()) {
        auto* player = item->as<bl::nbt::compound_tag>();
        // ...
    }
}

Working with This Codebase

• Always read existing code patterns before implementing new features.
• Prefer editing existing files over creating new ones.
• Keep bedrock-level/ free of Qt dependencies.
• When modifying chunk loading: test with worlds from multiple MCBE versions (1.18+, 1.19+, 1.20+, 1.21+).
• Check the TODO.md for planned features and known bugs before starting work.
• Reference docs/BedrockMap.md for detailed architecture docs.
• Reference docs/BedrockLevelFormat.md for MCBE level format specifics.

Terminal Commands

• Build + run: .\scripts\build_run.ps1
• Build only: .\scripts\build.ps1
• Run only (no build): .\scripts\run.ps1
• Quick incremental rebuild (skip lupdate / translation update): cmake --build build --config Debug -j 32
• Translation update: lupdate .\ -ts .\translations\zh_CN.ts .\translations\en.ts