Epic: Refresh Overworld Block and Biome Roadmap

[MichaelFisher1997]

Summary

Supersedes #138 and #139 with an implementation-focused roadmap for blocks, render shapes, biome definitions, and biome decoration.

Current State

• Block registry and data-driven block definitions exist under modules/world-core.
• Cross/billboard vegetation rendering is implemented via RenderShape.cross and the cross mesher.
• Current block IDs use u8 with MAX_BLOCK_TYPES = 256.
• Current overworld biome registry has 21 biome definitions.
• Existing biome generation supports terrain, surface/filler blocks, colors, vegetation densities, and tree profiles.

Goals

• Keep roadmap tracking aligned with the current codebase.
• Prioritize overworld gameplay and visual variety before Nether, End, and cave biomes.
• Split work into small issues with clear dependencies.
• Decide block ID capacity before expanding toward the old 322-block roadmap.

Non-Goals For First Phase

• Nether biomes.
• End biomes.
• Full decorative/building block parity.
• Mobs and structures.

Sub-Issues

Phase 0: Foundation Decisions

These can run in parallel.

• [Phase 0A] Blocks: Decide block ID capacity policy #621 - [Phase 0A] Blocks: Decide block ID capacity policy
• [Phase 0B] Blocks: Audit roadmap against current registry #622 - [Phase 0B] Blocks: Audit roadmap against current registry

Phase 1: Shared Foundations

These can run in parallel with Phase 0, but should land before dependent Phase 2/3 work.

• [Phase 1A] Rendering: Add flat quad and tall cross shapes #623 - [Phase 1A] Rendering: Add flat quad and tall cross shapes
• [Phase 1B] Worldgen: Generalize biome decoration profiles #624 - [Phase 1B] Worldgen: Generalize biome decoration profiles

Phase 2: Block, Aquatic, and Render Packs

These can run in parallel once their listed dependencies are ready.

• [Phase 2A] Blocks: Add core natural block pack #625 - [Phase 2A] Blocks: Add core natural block pack
• [Phase 2B] Aquatic: Add underwater vegetation and coral foundation #626 - [Phase 2B] Aquatic: Add underwater vegetation and coral foundation
• [Phase 2C] Rendering: Add attached and custom geometry shape foundation #627 - [Phase 2C] Rendering: Add attached and custom geometry shape foundation

Phase 3: Biome Expansion

These are intended as parallel biome implementation tracks after the relevant block, render-shape, aquatic, and decoration foundations exist.

• [Phase 3A] Biomes: Add cold and coastal variants #628 - [Phase 3A] Biomes: Add cold and coastal variants
• [Phase 3B] Biomes: Add forest and taiga variants #629 - [Phase 3B] Biomes: Add forest and taiga variants
• [Phase 3C] Biomes: Add mountain variants #630 - [Phase 3C] Biomes: Add mountain variants
• [Phase 3D] Biomes: Add tropical and arid variants #631 - [Phase 3D] Biomes: Add tropical and arid variants

Dependency Notes

• [Phase 0A] Blocks: Decide block ID capacity policy #621 and [Phase 0B] Blocks: Audit roadmap against current registry #622 can start immediately.
• [Phase 1A] Rendering: Add flat quad and tall cross shapes #623 and [Phase 1B] Worldgen: Generalize biome decoration profiles #624 can start immediately and are split so rendering and worldgen work can proceed independently.
• [Phase 2A] Blocks: Add core natural block pack #625 depends on [Phase 0A] Blocks: Decide block ID capacity policy #621, [Phase 0B] Blocks: Audit roadmap against current registry #622, and [Phase 1A] Rendering: Add flat quad and tall cross shapes #623.
• [Phase 2B] Aquatic: Add underwater vegetation and coral foundation #626 depends on [Phase 1A] Rendering: Add flat quad and tall cross shapes #623 and [Phase 1B] Worldgen: Generalize biome decoration profiles #624.
• [Phase 2C] Rendering: Add attached and custom geometry shape foundation #627 depends on [Phase 1A] Rendering: Add flat quad and tall cross shapes #623.
• [Phase 3A] Biomes: Add cold and coastal variants #628 depends on [Phase 1B] Worldgen: Generalize biome decoration profiles #624, [Phase 2A] Blocks: Add core natural block pack #625, and [Phase 2B] Aquatic: Add underwater vegetation and coral foundation #626.
• [Phase 3B] Biomes: Add forest and taiga variants #629 depends on [Phase 1A] Rendering: Add flat quad and tall cross shapes #623, [Phase 1B] Worldgen: Generalize biome decoration profiles #624, and [Phase 2A] Blocks: Add core natural block pack #625.
• [Phase 3C] Biomes: Add mountain variants #630 depends on [Phase 1B] Worldgen: Generalize biome decoration profiles #624 and [Phase 2A] Blocks: Add core natural block pack #625.
• [Phase 3D] Biomes: Add tropical and arid variants #631 depends on [Phase 1B] Worldgen: Generalize biome decoration profiles #624, [Phase 2A] Blocks: Add core natural block pack #625, and [Phase 2B] Aquatic: Add underwater vegetation and coral foundation #626.

Notes From Superseded Issues

• Block Types: Terrain & Vegetation Roadmap #138 was useful as a broad block catalogue, but it is now stale: cross/billboard rendering was completed in [Batch 1] Billboard/cross-model rendering for vegetation #373, paths moved to modules/*, and the 322-block scope exceeds the current 256-ID block storage cap.
• Biomes: Complete Biome Roadmap & Block Assignments #139 remains useful reference material, but it mixes implemented overworld biomes, future dimensions, structures, mobs, and block dependencies. This epic keeps the overworld roadmap while splitting implementation into dependency-ordered work.

[github-actions]

The epic accurately reflects the current codebase state:

Validated findings:

• BlockType (block.zig:76) is enum(u8) with ~47 entries defined, leaving ~200+ IDs before hitting the 256 cap — capacity decision isn't urgent.
• RenderShape (block_registry.zig:31) has only .cube and .cross — the roadmap's render shape expansion is valid.
• Biome enum (block.zig:9) has exactly 21 values (lines 10–31), matching the epic's count.

Architecture note not in the epic:
The codebase has two biome systems coexisting:

1. Legacy Biome enum (block.zig) — used by getSurfaceBlock/getFillerBlock
2. Data-driven BiomeDefinition (worldgen/biome.zig) — the modern system

The epic correctly focuses on the overworld-first scope and dependency ordering. For the first sub-issue (Block ID capacity), I'd suggest the decision be: "stay under 256 until >200 types exist, then widen to u16 with a palette layer" — rather than adding remapping complexity prematurely.

The sub-issues are well-scoped. Consider splitting the render shape expansion into two: one for flat_quad/tall_cross (simpler, cross-adjacent), and one for wall_attached/custom geometry (requires face-attachment state). These have different implementation complexity and could land in separate PRs.

opencode session  |  github run