ESPcraft

A work-in-progress Minecraft-like voxel game/client for ESP32, redesigned as a new voxel engine targeting ESP32-S3 and the new ESP32-S31 (dual-core 320 MHz RISC-V, 512 KB SRAM, 250 MHz DDR PSRAM, 60 GPIO, Wi-Fi 6 / BT 5.4 / Ethernet).

Hardware

Target platforms:

• ESP32-S3 (current dev)
• ESP32-S31 (next-gen, announced 2026; 320 MHz dual-core RISC-V, 512 KB SRAM, 8-bit 250 MHz DDR PSRAM)
• TFT display using TFT_eSPI
• Development board: any ESP32-S3 / ESP32-S31 with PSRAM and TFT

Repository

• espcraft.ino — new voxel engine (replaces legacy prototype)
• spritesheet.bmp — programmer-art spritesheet (8×8 tiles, 16×16 px each, 24-bit BMP)
• spritesheet.h — embedded RGB565 atlas array (PROGMEM), includes black/purple fallback
• 3d_render/ — legacy/prototype wireframe renderer (archival reference only)
• generation_lut/ — legacy LUT generator (archival reference only)
• ESP32-S31 hardware reference assets (from espressif/kicad-libraries#233, created by blobcoder21):
  • footprints/Espressif.pretty/ESP32-S31-QFN.kicad_mod (QFN package footprint)
  • symbols/Espressif.kicad_sym (symbol library, includes ESP32-S31 reference)
  • 3dmodels/espressif.3dshapes/ESP32-S31-QFN.STEP (3D model, 1.8 MB, FreeCAD 7.9, QFN 80 0.35 mm pitch 8×8 mm) These are authoritative reference assets for the ESP32-S31 QFN package and should not be regenerated from descriptions.

New Engine Features

• Configurable sprite atlas: ATLAS_TILE_PX, BLOCK_TILE_W, BLOCK_TILE_H, ATLAS_TILES_W, ATLAS_TILES_H are fully configurable. Changing them does not require rewriting the renderer.
• Built-in spritesheet loader: spritesheet.h provides an embedded PROGMEM array with basic programmer-art textures (solid colors + one checkered tile). A real spritesheet can replace this array or be loaded from external storage.
• Classic black/purple fallback: missing or out-of-bounds texture references return FALLBACK_BLACK (0x0000) and FALLBACK_PURPLE (0xF81F).
• Pre-baked Perlin continuous terrain: generateWorld() creates layered stone/dirt/grass terrain with decorative trees at startup.
• Chunk-based voxel world: CHUNK_SIZE 8, expandable to multi-chunk.
• Filled voxel rendering with basic face shading (lighter top, darker bottom, medium sides) and black edge outlines.
• Camera: yaw/pitch rotation, perspective projection (FOV 64, NEAR_CLIP 0.25).
• AABB collision (checkVoxelCollision, resolveCollision).
• Block interaction hooks: interactBreak() (raycast), interactPlace() (distance check).
• Serial input (w/a/s/d move, b break, p place, q/e yaw, r/f pitch).
• GPIO stub (handleGPIOInputStub) for ESP32-S3 / ESP32-S31 device-specific buttons.

Texture System Design

The renderer is designed so that textures can be added without rewriting it:

• BlockDef defines flatColor (fallback), texTileX, and texTileY (atlas reference).
• getFaceColor() samples from the atlas array using the block's texture reference.
• Each block texture spans BLOCK_TILE_W × BLOCK_TILE_H tiles in the atlas.
• The atlas dimensions and tile dimensions are pure configuration (#define).

To upgrade to real textures:

1. Replace or extend SPRITESHEET_DATA in spritesheet.h, or load from SD/PSRAM at runtime.
2. Adjust BlockDef::texTileX / texTileY to point to the new texture region.
3. Optionally replace getFaceColor() with per-pixel atlas sampling for full textured faces.

Status

Experimental / actively redesigned. The legacy renderer in 3d_render/ is preserved only as reference architecture. The new espcraft.ino is the primary development target.