Getting started

1. Open any folder that contains source files you want to explore in 3D.

2. Build and install the VSCode extension:

cd vscode-extension

npm install

npm run build-install-test

Tip

Robust One-Liner: Use this command to build and install correctly, regardless of whether you are in the project root or the vscode-extension directory:

[ "${PWD##*/}" = "vscode-extension" ] || cd vscode-extension && npm run build-install-test

3. If VSCode prompts you in the Extensions sidebar, restart extensions using the UI button.

4. Start OpenAs3D using the VSCode Command Palette and running:

>OpenAs3D: Open as 3D World

The current workspace will be opened as a navigable 3D world.

Controls

Movement:

• W, A, S, D: Move Forward, Left, Backward, Right
• Space: Jump (or Move Up in Flight Mode)
• C: Move Down (in Flight Mode)
• F: Toggle Flight Mode
• Mouse Move: Look around

Interaction:

• Click: Lock cursor / Select object (Code File)
• Double Click: Open file in VS Code editor
• Esc: Release cursor / Exit 3D view

Tools:

• E: Toggle Sign Placement Mode
  • Click (while in mode): Place a sign at the cursor location.
  • Double Click (on a sign): Edit sign text (opens Markdown file).

About OpenAs3D

This is an experiment in transforming real software systems into explorable 3D spaces.

The core idea: complex systems are often easier to understand as places rather than lists, trees, or diagrams. OpenAs3D investigates what happens when a codebase is treated as a navigable environment instead of a static set of files.

This repository contains the source for a Visual Studio Code extension that renders your codebase as a 3D world. Files become spatial objects you can inspect and reason about using video game–like navigation. Worlds can be loaded per workspace, and multiple worlds can coexist, allowing you to explore different parts of a system simultaneously.

OpenAs3D is not a game—it’s a developer tool and cognitive interface. Its goal is insight, orientation, and faster comprehension of structures and relationships that are difficult to grasp in text alone.

Guiding principles:

• Systems are places, not diagrams.

• Exploration precedes explanation.

• Spatial memory reduces cognitive load.

• Worlds are integrated into your IDE workflow.

OpenAs3D is a greenfield exploration of a “spatial IDE”—built on real developer workflows rather than replacing them. The experience may feel unexpected at first, but it quickly becomes intuitive and revealing.

Contributing

We welcome contributions from humans and AI agents! Please see our Contributing Guide for details on our development workflow and commit message standards.

Integrated Features

• Theme Synchronization: The 3D world automatically adapts to your current VS Code color theme.
• Architecture Analysis: An "Architecture Issues" panel appears in the bottom-right corner if dependency cycles or violations are detected (powered by dependency-cruiser).

Repository Structure

Note

AI Generated Content Disclosure The following repository structure overview was generated by an AI assistant. While based on a comprehensive analysis, users should verify specific details against the actual codebase.

The core logic resides in vscode-extension/, which contains the source code, tests, and configuration for the extension.

• src/core/: The domain model and business logic.

  • analysis/:
    • architecture-analyzer.ts: Integrates with dependency-cruiser to analyze codebase architecture and identify violations.
  • domain/:
    • code-file.ts: Represents a file in the codebase with its metadata and metrics.
    • code-entity.ts: Base class for code elements (files, classes, functions).
    • zone.ts: Defines architectural zones (e.g., source, tests, config) for layout organization.

• src/visualizers/: Logic for translating code structure into 3D spatial layouts.

  • codebase-layout.ts: Implements the zone-based layout algorithm to position files in 3D space.
  • codebase-analyzer.ts: Scans the filesystem and builds the dependency graph for visualization.

• src/webview/: The frontend 3D engine powered by Three.js.

  • world.ts: The main entry point and coordinator for the 3D scene.
  • objects/:
    • file-object.ts: The 3D mesh representation of a file, handling its visual appearance.
    • sign-object.ts: Renders user-placed 3D signs (experimental feature).
    • visual-object.ts: Base class for all interactable 3D objects.
  • character-controller.ts: Handles first-person movement (WASD) and input logic.
  • interaction-controller.ts: Manages user input (mouse, pointer lock) for object selection and sign placement.
  • code-object-manager.ts: Manages the lifecycle and rendering of all 3D code objects.
  • dependency-manager.ts: Handles the visualization of dependency lines (edges) between objects.
  • scene-manager.ts: Manages the Three.js scene graph, lighting, and camera configuration.

• src/services/:

  • description-sync-service.ts: Watches for external Markdown description files (e.g. in .3d-descriptions/) and syncs them to object labels.
  • editor-config-service.ts: Syncs VS Code editor settings (font size, font family, line height) to the 3D view.
  • explore-dependencies-service.ts: Orchestrates the 3D visualization workflow: initializes the webview panel, triggers codebase analysis (CodebaseAnalyzer), and pipes performance metrics to the UI.
  • sign-service.ts: Manages persistence of 3D signs to Markdown files (experimental feature).

• src/utils/:

  • file-system.ts: Wrapper for VS Code file system API operations.
  • languageRegistry.ts: Maps file extensions to programming languages and their associated colors.
  • perf-tracker.ts: Simple in-memory performance profiling utility for development.
    • Current Limitations: Unbounded memory usage (stores all samples), lack of hierarchical tracing, and data is lost on reload.
    • Future Improvements:
      • Limit memory usage: Switch to circular buffers so we only keep recent data instead of everything.
      • Better visualization: Add flame graphs to visually see which functions are slowing things down.
      • Save data: Add persistent export so you can save performance logs to a file for later analysis.

TDD Feedback Loop

OpenAs3D provides real-time visual feedback for your TDD cycle. When tests fail, the corresponding file objects in the 3D world will pulse red and shoot a laser beam into the sky.

Trying it Out

You can verify the TDD loop using the ZoneClassifier Priority test suite, which ensures that core business logic (Services/Domain) is prioritized over generic utilities (Lib) in the 3D layout.

1. Break the Implementation

1. Open vscode-extension/src/visualizers/zone-classifier.ts.
2. Swap the priority of the CORE (Section 7) and UTILITIES (Section 8) blocks.
3. Run the TDD tool in the 3D world (bottom-left panel).
4. Notice the src/services/user-util-service.ts object turns red in 3D because the test now fails (it's misclassified as lib).

2. Break the Test

1. Open vscode-extension/src/visualizers/__tests__/zone-classifier-priority.test.ts.
2. Change the expected value in the first test from 'core' to 'lib'.
3. The test will fail because the implementation correctly classifies it as core.
4. Observe the failure alert in the 3D environment.

3. Fix and Verify

1. Revert your changes to see the 3D alerts disappear and the status return to "Passed".

Hyper-Fast Extension Development (Hot Reload)

If you are developing OpenAs3D itself, you can enable Hot Reload to see your changes reflected instantly without manual packaging.

1. Setup Symlink

To avoid packaging a .vsix for every change, symlink your project folder directly into the VS Code extensions directory:

# Run from the root of the repository
ln -s "$(pwd)/vscode-extension" ~/.vscode/extensions/openas3d-dev

2. Enable Hot Reload

1. Open the OpenAs3D repository in VS Code.
2. Open the Command Palette (Cmd+Shift+P) and run:

   >OpenAs3D: Development: Toggle Hot Reload
   

3. Start the build watcher in your terminal:

   cd vscode-extension && npm run watch

Now, whenever you save a change to the extension source code, Webpack will recompile extension.js, and the extension will automatically reload the VS Code window for you.