The Voxel Workshop

verifiedAgainst f1eaefe · verifiedOn 2026-09-10 · the automated staleness banner is planned, not built.

In one paragraph

The Voxel Workshop is the single entry point for all custom Unity Editor tooling in Voxamine (Tools ▸ Voxel Sandbox ▸ Voxel Workshop). Rather than scattering ad-hoc windows, inspector buttons, and menu items across the Editor, all diagnostic and authoring tools are structured as modules implementing IWorkshopModule. The workbench is hosted by VoxelWorkshopWindow, which builds a UI Toolkit header, toolbar, and module switcher. Modules are registered centrally in WorkshopModuleRegistry and adhere to a strict two-stage lifecycle: CreateView() builds the visual hierarchy once, while Refresh() queries live runtime or asset state on demand. By convention, workshop modules are diagnostic or authoring lenses: they inspect and validate data through the same public APIs used by the game, keeping editor code strictly decoupled from runtime assemblies.

The pieces

Symbol	File	Responsibility
VoxelWorkshopWindow	Editor/VoxelWorkshop/Core/VoxelWorkshopWindow.cs:15	The host EditorWindow: builds root UI Toolkit chrome, manages the active module, remembers user module preference in EditorPrefs, and invokes Refresh()
IWorkshopModule	Editor/VoxelWorkshop/Core/IWorkshopModule.cs:5	The contract for all workshop tools: Id, DisplayName, Description, CreateView(), and Refresh()
WorkshopModuleRegistry	Editor/VoxelWorkshop/Core/WorkshopModuleRegistry.cs:24	Flat factory registry providing the ordered list of all 18 workshop modules
ProjectDoctorModule	Editor/VoxelWorkshop/Modules/ProjectDoctor/ProjectDoctorModule.cs:11	Default module: displays project hygiene and repository health checks, with quick fixes for common configuration drift
ProjectDoctorScanner	Editor/VoxelWorkshop/Modules/ProjectDoctor/ProjectDoctorScanner.cs:10	Automated rule scanner: checks project roots, HDRP baseline (17.5.0), linear color space, gitignore, build targets, and vendor asset ledger compliance

The module catalog

The 18 registered modules in WorkshopModuleRegistry.cs:26 span five distinct functional areas:

Domain	Module	Identifier	Purpose
Diagnostics & Health	Project Doctor	project-doctor	Validates repository paths, HDRP packages, color space, serialization modes, and asset ledger compliance
	Persistence Lab	persistence-lab	Inspects local save slots, displays slot metadata, and exercises atomic .bak corruption recovery
	Stream Monitor	stream-monitor	Live monitoring of chunk streaming queues, generation budgets, meshing throughput, and lifecycle transitions
Data & Content Authoring	Block Library	block-library	Validates BlockCatalog, inspects block definitions, stable IDs, solidity, and composition bridges
	Item Library	item-library	Validates ItemCatalog, stack rules, tool categories, and item-to-block associations
	Inventory Lab	inventory-lab	Tests inventory container math, slot stacking, and transfer rules against active catalogs
	Texture Foundry	texture-foundry	Generates procedural block textures and normal maps directly from C# recipes into Assets/_Game/Textures/
	Model Foundry	model-foundry	Tools for procedural block and apparatus mesh generation
	Scene Composer	scene-composer	Validates required scene hierarchy objects, camera rigs, and HUD settings assets
World & Simulation	World Studio	world-studio	Visual tuning and slicing for terrain noise, height bands, climate distribution, and ore strata
	Chunk Lab	chunk-lab	Inspects individual chunk meshing, greedy quad merging, face counts, and vertex normals
	Weather Lab	weather-lab	Controls and monitors the simulation’s dynamic precipitation, cloud cover, and soil moisture
	Graphics Lab	graphics-lab	Verifies HDRP volume overrides, lighting, shadow cascades, and fog profiles
	Enemy Lab	enemy-lab	Previews enemy prefabs, animation rigs, hitboxes, and sensor profiles
Audio	Sfx Studio	sfx-studio	Synthesizes and auditions retro-procedural sound effects via Tools/AudioGen bindings
Science & Reactions	Chemistry Lab	chemistry-lab	Validates SubstanceCatalog and ReactionCatalog, evaluating thermodynamic Shomate curves ($C_p$, $S^\circ$, $H$)
	Assay Lab	assay-lab	Inspects ore grade distributions, mineral yields, and sample assay readings across biomes
	Electrochemistry Lab	electrochemistry-lab	Evaluates half-cell potentials ($E^\circ$), Nernst equations, and electrode reactions

The flow

flowchart TD
  MENU["Tools ▸ Voxel Sandbox ▸ Voxel Workshop\n[MenuItem] Open()"]
  WINDOW["VoxelWorkshopWindow\nCreateGUI()"]
  REGISTRY["WorkshopModuleRegistry\nCreateModules()"]
  HEADER["Header & Toolbar\nModule Dropdown + Refresh Button"]
  ACTIVATE["Activate(module)\nSwitch Content View"]
  VIEW["module.CreateView()\nreturns VisualElement"]
  REFRESH["module.Refresh()\npopulates live state"]
  PREFS["EditorPrefs\nstore preferredModuleId"]

  MENU --> WINDOW
  WINDOW --> REGISTRY
  REGISTRY --> WINDOW
  WINDOW --> HEADER
  WINDOW --> ACTIVATE
  ACTIVATE --> VIEW
  ACTIVATE --> REFRESH
  ACTIVATE --> PREFS
  HEADER -. user selects new tab .-> ACTIVATE
  HEADER -. user clicks Refresh .-> REFRESH

1. Unified lifecycle

When VoxelWorkshopWindow.Open() runs (VoxelWorkshopWindow.cs:28), Unity displays an EditorWindow docked or floating with a minimum size of 680×420. In CreateGUI(), the window instantiates all modules via WorkshopModuleRegistry.CreateModules() (WorkshopModuleRegistry.cs:48). It checks EditorPrefs for the last-used module ID (defaulting to ProjectDoctorModule.ModuleId) and calls Activate().

2. View construction vs data refresh

Every module implements IWorkshopModule (IWorkshopModule.cs:5):

• CreateView(): Builds the UI Toolkit element hierarchy (using standard UIElements like ScrollView, Label, Button, Foldout, and HelpBox). It is called only when the module becomes active and should perform zero expensive computations or disk scans.
• Refresh(): Populates the UI widgets with fresh data. It is invoked immediately after CreateView() on activation and whenever the user clicks the toolbar’s Refresh button or changes a filter control.

3. Automated repository governance (Project Doctor)

ProjectDoctorModule serves as the repo’s automated sanity check. Clicking “Run Doctor” triggers ProjectDoctorScanner.Scan() (ProjectDoctorScanner.cs:18), which asserts:

• The project folder is named Minecraft-HD.
• Core folders (Assets/_Game, Assets/_Game/Scripts, Assets/_Game/Editor/VoxelWorkshop) exist.
• Unity editor version matches ProjectSettings/ProjectVersion.txt.
• High Definition Render Pipeline (com.unity.render-pipelines.high-definition) is pinned to 17.5.0.
• Color space is set to ColorSpace.Linear.
• Third-party packages in Assets/ThirdParty/ are fully recorded in Docs/ASSET_LEDGER.md with explicit license tracking and quarantine boundaries.

Invariants you must not break

1. No rogue menu items. Never create new top-level [MenuItem("Tools/...")] or [MenuItem("Window/...")] actions for diagnostics or authoring. Every new tool must be registered as an IWorkshopModule within WorkshopModuleRegistry.
2. CreateView() must be lightweight. Build the visual hierarchy and bind event listeners, but never execute synchronous asset scans, disk searches, or simulation ticks inside CreateView(). Defer data population to Refresh().
3. Modules are diagnostic views, not state owners. Workshop modules inspect runtime managers, evaluate catalogues, or run preview simulations. They must not introduce secondary or shadow authoritative states that diverge from production runtime components.
4. Editor UI uses UI Toolkit (UnityEngine.UIElements). Workshop modules are authored with modern UI Toolkit elements, styled cleanly to match Unity’s dark theme. Do not write legacy IMGUI (GUILayout/EditorGUILayout) inside workshop views.
5. Honor the assembly boundary. VoxelSandbox.Editor references runtime assemblies down the dependency chain, but runtime assemblies never reference editor modules.

Where it connects

• Upstream: Every runtime assembly (Data, World, Chemistry, Inventory, Player, Industry) supplies the public APIs, models, and catalogues inspected by the workshop labs.
• Downstream: VoxelSandbox.Editor encapsulates all workshop views and scanners. No runtime code depends on IWorkshopModule or VoxelWorkshopWindow.
• Validation: The workshop provides interactive visual verification for workflows:
  • Adding a block uses Block Library and Texture Foundry.
  • Adding a chemical route uses Chemistry Lab.
  • Modifying persistence uses Persistence Lab.
  • Tuning terrain uses World Studio and Chunk Lab.

See also

• Catalogues & authoring — the data catalogue architecture evaluated by the Block, Item, and Chemistry labs.
• The runtime UI — contrasts the in-game UGUI runtime against the editor-only UI Toolkit workshop architecture.
• Assemblies & boundaries — explains the assembly boundary isolating editor tools from shipped runtime code.
• Docs/BUILD_AND_TEST.md — instructions for running headless tests and project builds.