Use polyhedral “dice” shapes to encode code object semantics in 3D world

[bitkojine]

Feature Request: Semantic Geometry & Functional Shape Ontology (Replacing "Generic Boxes")

Context & Problem

Currently, OpenAs3D renders all code objects (files, classes, modules) as simple rectangular boxes. While height effectively conveys scale (LOC), the uniformity fails to convey intent or behavior.

A massive DTO (Data Transfer Object) looks identical to a massive "God Class" Controller, despite having completely different architectural implications. To understand the system, the user is forced to inspect objects individually rather than reading the system's topology at a glance.

Proposed Solution

Replace the generic box model with a Functional Shape Ontology. Instead of arbitrary shapes, we map geometric archetypes to code responsibilities.

The goal is to move from "Systems as Diagrams" to "Systems as Landscapes," where the shape of an object intuitively communicates its role (storage vs. processing vs. routing).

1. Shape Archetypes (The "What")

We should categorize code objects into three distinct geometric families to create recognizable silhouettes:

• The Block (Cube/Prism) → State & Data
  • Usage: DTOs, Configs, Database Models, Structs.
  • Visual Semantics: Stable, stackable, heavy. Grounded.
• The Crystal (Pyramid/Diamond) → Logic & Processing
  • Usage: Services, Utilities, Algorithms, Pure Functions.
  • Visual Semantics: Sharp, directional (pointing input to output), active.
• The Node (Polyhedra/Platonic Solids) → Hubs & Interfaces
  • Usage: Controllers, Facades, API Endpoints, Modules.
  • Visual Semantics: Multi-faceted. The number of faces (d8, d12, d20) represents the "surface area" of the API or coupling degree.

2. Material & Texture Encodings (The "How")

Visual attributes should encode the health and lifecycle of the code, utilizing shader properties rather than just flat colors.

• Churn / Hot Paths: High recent commit activity → Emissive/Glowing. The code looks "hot."
• Legacy / Stable: Unchanged for >1 year → Roughness/Stone texture. The code looks "settled" or like bedrock.
• Deprecated / Risk: → Wireframe or Ghost transparency.
• Complexity: Do not just increase size. Increase Fractal Density. A simple function is smooth; a complex one has surface imperfections or "greebling."

3. Visual Hierarchy (LOD)

To maintain performance and readability:

• Far Distance: Objects simplify to low-poly primitives or points. Color encodes Domain (e.g., Auth, Payments).
• Mid Distance: Distinct shapes (Block vs. Crystal) become legible.
• Close Distance: Surface details (fractals, heat emission) resolve.

User Stories

• "As a developer, I want to scan a directory and immediately distinguish which files are simple data structures versus complex logic processors based on their shape."
• "As a lead, I want to identify 'God Objects' by looking for high-face-count Polyhedra (d20s) that are glowing (high churn), indicating a risk hotspot."

Implementation & Performance Constraints

• Instanced Rendering: Must use GPU instancing. We cannot have unique geometries for every file. We need a limited library of ~10-15 base meshes that are scaled/colored via instance attributes.
• Colors: strict palette usage. Avoid "rainbow soup." Color should be reserved for Domain/Language, not Metrics.

Open Questions

• Hybrid Objects: How do we render a file that contains both heavy state and heavy logic? (Default to the "riskier" shape?)
• Mapping Configuration: Should we provide a .openas3drc JSON map for users to define their own regex-to-shape rules?