Random Block Walk

================================================================================

  RANDOM BLOCK WALK ADDON | OFFICIAL DOCUMENTATION & USER GUIDE

  Minecraft Bedrock Edition (Script API @minecraft/server)

================================================================================

 

[GENERAL INFORMATION]

* Addon Name : Random Block Walk

* Creator / Author: Nute MC²

* Version : 1.3.0 (Ultra Performance & Expanded Edition)

* Minimum Engine : Minecraft Bedrock 1.21.110+

* Script API : @minecraft/server v1.17.0+

* Modules : Behavior Pack (BP) & Resource Pack (RP)

 

================================================================================

 1. OVERVIEW & CONCEPT

================================================================================

Random Block Walk is an ultra-fun, chaotic, and unpredictable challenge addon 

designed for Minecraft Bedrock Edition. Every single time a player moves, jumps, 

or lands on solid ground, the block immediately underneath their feet is 

randomly replaced with a different block from a massive pool of over 320+ solid 

block types.

 

Whether you are traversing mountains, exploring deep caves, or building a base, 

your footsteps will leave behind a trail of netherite, glass, TNT, terracotta, 

ores, or rare 1.21 Trial Chamber blocks!

 

================================================================================

 2. KEY FEATURES & HIGHLIGHTS

================================================================================

* Massive Block Pool (320+ Blocks):

  - Fully supports blocks from early Minecraft up to the latest 1.21+ updates 

    (including Pale Garden, Resin blocks, Trial Chambers, Copper variants, etc.).

 

* Extreme Performance Overhaul (v1.3.0):

  - Pre-cached Permutations: Boosts runtime execution efficiency by up to 300% 

    by eliminating heavy runtime resolution calls.

  - O(1) Block Selection: Instant random selection with zero CPU spikes.

  - Memory Leak Protection: Automatically purges inactive player data upon 

    leaving the world to ensure zero memory buildup on servers and Realms.

 

* Smart Movement Detection:

  - Grid Coordinates Logic: Only triggers block updates when a player crosses 

    into a NEW block grid coordinate (X, Y, Z), eliminating rapid, redundant 

    flickering when moving slowly inside a single block.

  - Zero Math.sqrt CPU Overhead: Utilizes a squared Euclidean distance algorithm.

 

* Multi-Environment & Multiplayer Support:

  - Works seamlessly in Singleplayer worlds, LAN games, Dedicated Servers, 

    and Minecraft Realms.

  - Tracks multiple players independently without server tick lag.

 

================================================================================

 3. DETAILED TECHNICAL ARCHITECTURE & PERFORMANCE OPTIMIZATIONS

================================================================================

To maintain a stable 20 TPS (Ticks Per Second) environment, version 1.3.0 

re-architected the entire Script API execution model:

 

1. Pre-caching BlockPermutations:

   - Traditional script addons invoke `BlockPermutation.resolve(id)` every time 

     a block changes, causing CPU bottlenecks.

   - Version 1.3.0 resolves all valid block IDs into an array of 

     `BlockPermutation` objects ONCE during world load. During gameplay, the 

     script simply fetches pre-compiled objects from RAM in O(1) constant time.

 

2. Elimination of Square Root Operations:

   - Standard Euclidean distance logic requires calculating square roots:

     

     distance = sqrt(dx^2 + dz^2)

     

   - We replaced this with squared distance comparison:

     

     dist_squared = dx^2 + dz^2 >= THRESHOLD_SQUARED

     

   - This completely removes CPU-intensive square-root calculations from the main loop.

 

3. Grid Coordinate State Tracking:

   - Players moving inside a single 1x1 block boundary no longer trigger 

     excessive block updates.

   - The script tracks integer floor coordinates (X, Y-1, Z) and updates 

     blocks only when a block boundary is crossed or when landing after a jump.

 

================================================================================

 4. COMPREHENSIVE BLOCK POOL CATEGORIES (320+ BLOCKS)

================================================================================

The addon automatically purges forbidden/unsafe blocks (Air, Water, Lava, 

Structure Void, Unknown blocks) and supports:

 

1. Ores & Raw Minerals:

   - All Overworld & Deepslate Ores (Coal, Iron, Gold, Diamond, Emerald, Lapis, Redstone, Copper)

   - Nether Gold Ore, Nether Quartz Ore, Ancient Debris

   - Raw Iron Block, Raw Copper Block, Raw Gold Block

 

2. Precious Metals & Gem Blocks:

   - Coal, Iron, Gold, Diamond, Emerald, Netherite, Lapis, Redstone, Amethyst Blocks

 

3. Copper & Weathering Variants (Full 1.21 Set):

   - Regular, Exposed, Weathered, Oxidized Copper

   - Waxed variants of all copper stages

   - Cut Copper, Chiseled Copper, Copper Grates, Copper Bulbs

 

4. Dirt, Sand, Mud, Organic & Mushrooms:

   - Grass, Coarse Dirt, Podzol, Rooted Dirt, Mycelium, Sand, Red Sand, Gravel

   - Mud, Packed Mud, Mud Bricks, Moss, Pale Moss, Suspicious Sand/Gravel

   - Brown Mushroom Block, Red Mushroom Block, Mushroom Stem

 

5. Woods, Stripped Logs & Planks (12 Wood Types):

   - Oak, Spruce, Birch, Jungle, Acacia, Dark Oak, Mangrove, Cherry, Pale Oak, 

     Bamboo (including Bamboo Mosaic), Crimson, and Warped sets.

 

6. Leaves & Foliage:

   - All tree leaves including Azalea, Flowering Azalea, Cherry, Pale Oak.

 

7. Stone, Deepslate, Tuff, Basalt & Building Blocks:

   - Granite, Diorite, Andesite (and polished variants)

   - Stone Bricks, Cobblestone, Mossy Bricks

   - Deepslate, Cobbled Deepslate, Polished Deepslate, Deepslate Tiles/Bricks

   - Tuff, Polished Tuff, Tuff Bricks, Chiseled Tuff

   - Basalt, Smooth Basalt, Calcite, Dripstone Block

 

8. Concrete, Concrete Powder, Wool, Terracotta & Glazed Terracotta:

   - All 16 color variations for Wool, Concrete, Concrete Powder, Terracotta, 

     and Glazed Terracotta.

 

9. Glass & Tinted Glass:

   - Regular Glass, Tinted Glass, and all 16 Stained Glass variants.

 

10. Nether, End & Ocean Blocks:

    - Netherrack, Soul Sand, Soul Soil, Nether Bricks, Blackstone variants

    - Shroomlight, Warped/Nether Wart Blocks

    - End Stone, End Stone Bricks, Purpur Blocks/Pillars

    - Glowstone, Sea Lantern, Prismarine, Dark Prismarine, Froglights

    - All 5 Living Coral Blocks & Dead Coral Blocks

 

11. Functional & Special Update 1.21 Blocks:

    - Crafting Tables, Furnaces, Smokers, Blast Furnaces, Anvils, Bookshelves

    - Shulker Boxes (all 16 colors)

    - TNT, Sponge, Ice, Packed Ice, Blue Ice, Target, Lodestone, Respawn Anchor

    - Sculk, Sculk Catalyst, Sculk Sensor, Sculk Shrieker

    - Crafter, Vault, Trial Spawner, Heavy Core

    - Resin Block, Resin Bricks, Chiseled Resin Bricks (Pale Garden Update)

 

================================================================================

 5. VERSION HISTORY (DETAILED CHANGELOG)

================================================================================

 

* VERSION 1.3.0 (Ultra Performance & Expanded Edition)

  - [MAJOR OPTIMIZATION] Implemented full RAM pre-caching for BlockPermutations.

  - [MAJOR OPTIMIZATION] Replaced Euclidean distance calculation with Squared Distance logic.

  - [NEW BLOCKS] Expanded total block pool from 250+ to 320+ full solid blocks.

  - [FEATURE] Added full support for Minecraft 1.21+ blocks (Resin, Pale Oak, Trial Spawner, Heavy Core, etc.).

  - [BUG FIX] Resolved grid flickering where slow movement caused redundant block replacements in the same tile.

  - [BUG FIX] Fixed memory retention by deleting player tracking data upon disconnection.

 

* VERSION 1.2.0 (Expanded Edition)

  - [EXPANSION] Expanded block pool to 250+ full solid blocks.

  - [FEATURE] Added bilingual (English & Vietnamese) startup notifications in global chat.

  - [FEATURE] Improved falling/landing detection logic to trigger block placement instantly upon landing.

  - [OPTIMIZATION] Adjusted tick check interval to 4 ticks for optimal performance.

 

* VERSION 1.1.0 (Stability Update)

  - [FEATURE] Added dynamic runtime block resolution validation to prevent crashes from unsupported block IDs.

  - [SECURITY] Added `FORBIDDEN_BLOCKS` set to automatically filter Air, Cave Air, Void Air, Liquids, and Moving Blocks.

  - [EXPANSION] Expanded block selection list to 150+ types.

 

* VERSION 1.0.0 (Initial Release)

  - [RELEASE] First public release utilizing modern Minecraft Bedrock Script API (`@minecraft/server`).

  - [FEATURE] Basic movement tracking placing random dirt/stone under player feet.

 

================================================================================

 6. INSTALLATION & SETUP GUIDE

================================================================================

1. Download both required files:

   - `RandomBlockWalk_BP_v1.3.0.mcpack` (Behavior Pack)

   - `RandomBlockWalk_RP_v1.3.0.mcpack` (Resource Pack)

 

2. Import into Minecraft Bedrock:

   - Open/Double-click both files. Minecraft Bedrock will launch and automatically import them.

 

3. World Settings Configuration:

   - Go to your World Settings menu in Minecraft.

   - Under "Resource Packs" -> Activate "Random Block Walk (Resource Pack)".

   - Under "Behavior Packs" -> Activate "Random Block Walk".

   - CRITICAL REQUIREMENT: Scroll down to the "Experiments" section in World Settings and toggle ON "Beta APIs".

 

4. Launch & Play:

   - Enter your world. A global chat message will display the total number of cached blocks.

   - Start walking, sprinting, or jumping to enjoy the challenge!

 

================================================================================

 7. TROUBLESHOOTING & FREQUENTLY ASKED QUESTIONS (FAQ)

================================================================================

Q1: Why aren't blocks placing underneath me when I walk?

A1: Ensure that the "Beta APIs" experiment toggle is enabled in your World Settings. 

    Script API addons require Beta APIs to execute JavaScript properly.

 

Q2: Does this addon cause tick lag on low-end mobile devices or Realms?

A2: No! Version 1.3.0 is built with pre-compiled memory caching and runs in 

    a fraction of a millisecond per tick.

 

Q3: Is this compatible with Multiplayer, Dedicated Servers, and Realms?

A3: Yes! The script processes each player's movement independently and 

    cleans up memory when players leave.

 

Q4: Will I fall into the void when air blocks appear?

A4: Air, liquids, and void blocks are strictly excluded from the block pool, 

    ensuring you always have solid ground beneath your feet.

 

================================================================================

 8. CREDITS & TERMS OF USE

================================================================================

* Author / Creator : Nute MC²

* Engine Target : Minecraft Bedrock Edition (1.21.110+)

* Scripting API : @minecraft/server (Module v1.17.0+)

 

[TERMS OF USE]

- You are FREE to play, stream, and create content (YouTube, TikTok, Twitch) 

  using this addon.

- If showcasing this addon in videos or articles, please provide credit to 

  "Nute MC²" and direct viewers to the official download links.

- Re-uploading modified code or redistributing on unauthorized platforms 

  without author consent is prohibited.

 

================================================================================

                      Thank you for playing Random Block Walk!

================================================================================