[GH-ISSUE #3703] [Feature] Mobile world container reverse engineering: .mcworld, .mcpack, .mcaddon packages, Molang expressions, behavior schemas and Script API graphs #1414

New issue

Open

opened 2026-10-16 21:05:15 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:05:15 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3703

Problem Statement & Context

The cross-platform C++ mobile and bedrock implementation of voxel worlds relies on an entirely distinct container, storage, and entity-component architecture compared to the legacy desktop JVM format:

Packaging Formats (.mcworld, .mcpack, .mcaddon): Standard ZIP containers containing specialized directory conventions:
- manifest.json: Defines package UUIDs, versions, modules (data, resources, client_data, javascript), and dependencies.
- .mcaddon: Composite archive bundling corresponding behavior packs and resource packs together.
- .mcworld: Complete world package bundling world settings, player data, and the storage engine.
LevelDB World Backing Store (db/): World chunks, entity states, player inventories, and actor dictionaries stored as key-value pairs within a LevelDB database. Keys are structured using sub-chunk index tags, dimension prefixes, and actor storage keys.
Data-Driven Entity Behavior Packs: JSON schemas defining entity components (minecraft:health, minecraft:movement, minecraft:behavior.melee_attack, minecraft:environment_sensor).
Molang Expression Language: A lightweight, domain-specific mathematical expression language (query.is_sneaking ? 0.5 : 1.0, variable.speed = Math.sin(query.anim_time)) used across animation controllers, render controllers, and entity logic.
Script API Runtime: Embedded JavaScript/TypeScript modules interacting with the world simulation through @minecraft/server and @minecraft/server-ui.

REA currently lacks a dedicated analyzer for these mobile packages, LevelDB chunk keyspaces, Molang AST parsing, and behavior pack components.

Proposed Architecture

flowchart TD
    A[".mcworld / .mcpack / .mcaddon Archive"] --> B["Mobile World & Behavior Semantic Engine"]
    B --> C["Package & Manifest Validator"]
    B --> D["LevelDB World Storage Extractor"]
    B --> E["Behavior Pack & Molang AST Decompiler"]
    B --> F["Script API & Event Graph Reconstructor"]
    
    C --> C1["manifest.json Parsing (UUIDs, Modules, Dependencies)"]
    C --> C2["Pack Type Identification (Resource, Behavior, Addon)"]
    
    D --> D1["db/ LevelDB Sub-Chunk Key Decoding"]
    D --> D2["Actor / Entity NBT Deserialization"]
    
    E --> E1["Entity Component JSON Schema Validation"]
    E --> E2["Molang Mathematical Expression Parser & AST"]
    E --> E3["Animation & State Machine Controllers"]
    
    F --> F1["Script API JS Bundles (@minecraft/server)"]
    F --> F2["World Event Subscriptions (world.afterEvents)"]
    
    C & D & E & F --> G["Unified Mobile World Manifest & Behavioral Component Graph"]

Technical Capabilities & Modules

Package Container & Manifest Parsing:
- Unpack .mcworld, .mcpack, and .mcaddon ZIP containers.
- Parse and validate manifest.json: header metadata, UUID references, pack versioning, and module types (resources, data, script).
- Reconstruct dependencies between behavior packs and corresponding resource packs.
LevelDB World Keyspace Decoding (db/):
- Leverage REA's LevelDB engine (#3691) to parse the db/ world store.
- Decode key tag types:
  - Sub-chunk data: tag 0x2f (subchunk prefix), dimension IDs, subchunk Y-indices.
  - Actor / Entity storage: tag 0x30 (actorprefix) and raw NBT entity blobs.
  - Map data, ticking areas, and biome data keys.
Behavior Pack Entity Component Analysis:
- Parse entity definition JSONs (entities/*.json).
- Extract component groups, event triggers (minecraft:entity_spawned, minecraft:entity_born), and state transitions.
- Build a behavior graph mapping entity interactions and AI goal selectors.
Molang Expression Parsing & AST Reconstruction:
- Lex and parse Molang string expressions embedded in animation controllers and component definitions.
- Build an Abstract Syntax Tree (AST) supporting queries (query.*), variables (variable.*, temp.*), and math operators.
- Statically evaluate constant or deterministic expressions.
Script API Interfacing:
- Parse embedded JavaScript/TypeScript scripts within scripts/.
- Identify imports from official runtime modules (@minecraft/server, @minecraft/server-ui).
- Map event subscriptions (system.runInterval, world.afterEvents.entitySpawn, world.afterEvents.chatSend).

Acceptance Criteria

Automated validation and unpacking of .mcworld, .mcpack, and .mcaddon archives.
Parsing and cross-referencing of pack manifests, UUIDs, and module dependencies.
Decoding of LevelDB world keyspace into sub-chunks, entities, and world settings.
Extraction and structural validation of JSON entity behavior components.
Lexer and AST parser for embedded Molang expressions.
Identification and mapping of Script API event listeners and entrypoints.

Complements #3691 (Chromium LevelDB reverse engineering: SSTables, WAL history)
Complements #3701 (Anvil world container and NBT reverse engineering)

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3703 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Game & Engine RE](https://img.shields.io/badge/domain-game_&_engine_RE-green.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ### Problem Statement & Context The cross-platform C++ mobile and bedrock implementation of voxel worlds relies on an entirely distinct container, storage, and entity-component architecture compared to the legacy desktop JVM format: 1. **Packaging Formats (`.mcworld`, `.mcpack`, `.mcaddon`)**: Standard ZIP containers containing specialized directory conventions: - `manifest.json`: Defines package UUIDs, versions, modules (`data`, `resources`, `client_data`, `javascript`), and dependencies. - `.mcaddon`: Composite archive bundling corresponding behavior packs and resource packs together. - `.mcworld`: Complete world package bundling world settings, player data, and the storage engine. 2. **LevelDB World Backing Store (`db/`)**: World chunks, entity states, player inventories, and actor dictionaries stored as key-value pairs within a LevelDB database. Keys are structured using sub-chunk index tags, dimension prefixes, and actor storage keys. 3. **Data-Driven Entity Behavior Packs**: JSON schemas defining entity components (`minecraft:health`, `minecraft:movement`, `minecraft:behavior.melee_attack`, `minecraft:environment_sensor`). 4. **Molang Expression Language**: A lightweight, domain-specific mathematical expression language (`query.is_sneaking ? 0.5 : 1.0`, `variable.speed = Math.sin(query.anim_time)`) used across animation controllers, render controllers, and entity logic. 5. **Script API Runtime**: Embedded JavaScript/TypeScript modules interacting with the world simulation through `@minecraft/server` and `@minecraft/server-ui`. REA currently lacks a dedicated analyzer for these mobile packages, LevelDB chunk keyspaces, Molang AST parsing, and behavior pack components. ### Proposed Architecture ```mermaid flowchart TD A[".mcworld / .mcpack / .mcaddon Archive"] --> B["Mobile World & Behavior Semantic Engine"] B --> C["Package & Manifest Validator"] B --> D["LevelDB World Storage Extractor"] B --> E["Behavior Pack & Molang AST Decompiler"] B --> F["Script API & Event Graph Reconstructor"] C --> C1["manifest.json Parsing (UUIDs, Modules, Dependencies)"] C --> C2["Pack Type Identification (Resource, Behavior, Addon)"] D --> D1["db/ LevelDB Sub-Chunk Key Decoding"] D --> D2["Actor / Entity NBT Deserialization"] E --> E1["Entity Component JSON Schema Validation"] E --> E2["Molang Mathematical Expression Parser & AST"] E --> E3["Animation & State Machine Controllers"] F --> F1["Script API JS Bundles (@minecraft/server)"] F --> F2["World Event Subscriptions (world.afterEvents)"] C & D & E & F --> G["Unified Mobile World Manifest & Behavioral Component Graph"] ``` ### Technical Capabilities & Modules 1. **Package Container & Manifest Parsing:** - Unpack `.mcworld`, `.mcpack`, and `.mcaddon` ZIP containers. - Parse and validate `manifest.json`: header metadata, UUID references, pack versioning, and module types (`resources`, `data`, `script`). - Reconstruct dependencies between behavior packs and corresponding resource packs. 2. **LevelDB World Keyspace Decoding (`db/`):** - Leverage REA's LevelDB engine (#3691) to parse the `db/` world store. - Decode key tag types: - Sub-chunk data: `tag 0x2f` (subchunk prefix), dimension IDs, subchunk Y-indices. - Actor / Entity storage: `tag 0x30` (`actorprefix`) and raw NBT entity blobs. - Map data, ticking areas, and biome data keys. 3. **Behavior Pack Entity Component Analysis:** - Parse entity definition JSONs (`entities/*.json`). - Extract component groups, event triggers (`minecraft:entity_spawned`, `minecraft:entity_born`), and state transitions. - Build a behavior graph mapping entity interactions and AI goal selectors. 4. **Molang Expression Parsing & AST Reconstruction:** - Lex and parse Molang string expressions embedded in animation controllers and component definitions. - Build an Abstract Syntax Tree (AST) supporting queries (`query.*`), variables (`variable.*`, `temp.*`), and math operators. - Statically evaluate constant or deterministic expressions. 5. **Script API Interfacing:** - Parse embedded JavaScript/TypeScript scripts within `scripts/`. - Identify imports from official runtime modules (`@minecraft/server`, `@minecraft/server-ui`). - Map event subscriptions (`system.runInterval`, `world.afterEvents.entitySpawn`, `world.afterEvents.chatSend`). ### Acceptance Criteria - [ ] Automated validation and unpacking of `.mcworld`, `.mcpack`, and `.mcaddon` archives. - [ ] Parsing and cross-referencing of pack manifests, UUIDs, and module dependencies. - [ ] Decoding of LevelDB world keyspace into sub-chunks, entities, and world settings. - [ ] Extraction and structural validation of JSON entity behavior components. - [ ] Lexer and AST parser for embedded Molang expressions. - [ ] Identification and mapping of Script API event listeners and entrypoints. ### Related Issues & Dependencies - Complements #3691 (Chromium LevelDB reverse engineering: SSTables, WAL history) - Complements #3701 (Anvil world container and NBT reverse engineering)

bsakaguchi referenced this issue

2026-10-17 21:01:32 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-17 21:11:12 +00:00

[PR #1414] [CLOSED] test(javascript): preserve member-alias fanout and loop regressions #2868