Skip to main content

​
High-Level Architecture

Gitlantis is built as a VS Code extension with a webview-based UI. It consists of two main processes that communicate via message passing: 
┌─────────────────────────────────────────┐
│        VS Code Extension Host           │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │   Extension Process (Node.js)     │ │
│  │                                   │ │
│  │  • Command registration           │ │
│  │  • Webview panel management       │ │
│  │  • File system operations         │ │
│  │  • Git integration                │ │
│  │  • Message handling               │ │
│  └───────────────────────────────────┘ │
│               ↕ Messages                │
│  ┌───────────────────────────────────┐ │
│  │   Webview (Browser Context)       │ │
│  │                                   │ │
│  │  • React application              │ │
│  │  • Three.js 3D rendering          │ │
│  │  • Physics simulation             │ │
│  │  • User interactions              │ │
│  └───────────────────────────────────┘ │
└─────────────────────────────────────────┘

​
Extension Process

The extension process runs in Node.js and has full access to the VS Code API.

​
Entry Point (src/extension/index.ts)

The extension activates when:
  • VS Code starts up (onStartupFinished)
  • User runs the “Gitlantis” command
The activate() function:
  1. Registers commands via registerCommands()
  2. Launches the extension if previously active via launchExtension()

​
Command Registration (src/extension/commands/index.ts)

The extension registers a single command:
  • gitlantis.start - Launches the Gitlantis webview
Key responsibilities: Creating the Webview Panel 
const panel = vscode.window.createWebviewPanel(
  'gitlantis',
  'Gitlantis',
  vscode.ViewColumn.One,
  { enableScripts: true, retainContextWhenHidden: true }
)
Loading Webview Assets
  • Transpiled JavaScript from out/assets/
  • Public assets (images, audio)
  • Generates HTML with proper CSP (Content Security Policy)
State Persistence
  • Tracks if Gitlantis is active via globalState
  • Auto-restores on VS Code restart
  • Relaunches when workspace folder changes

​
Message Handling (src/extension/handlers/)

The extension responds to messages from the webview: File Operations
  • readDirectory - List files/folders in a directory
  • openFile - Open file in VS Code editor
  • openExplorer - Reveal file in VS Code Explorer
Git Operations (src/extension/handlers/git/)
  • listBranches - Get all git branches
  • checkoutBranch - Switch to a different branch
Settings (src/extension/handlers/handleSettings/)
  • getSettings - Retrieve user settings
  • updateSettings - Save user preferences
Message flow: 
panel.webview.onDidReceiveMessage((message) => {
  switch (message.type) {
    case 'readDirectory':
      // Handle directory read
      break
    case 'openFile':
      // Open file in editor
      break
    // ...
  }
})

​
Browser Process (Webview)

The webview runs a full React application with 3D rendering capabilities.

​
Entry Point (src/main/index.tsx)

Bootstraps the React app: 
createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ExtensionContextProvider>
      <World />
    </ExtensionContextProvider>
  </StrictMode>
)

​
Context Providers

ExtensionContext (src/browser/context/extension/)
  • Provides VS Code API access to components
  • Manages message passing with extension
  • Exposes helper functions for file operations
GameContext (src/browser/context/game/)
  • Manages global game state
  • Tracks boat position, camera settings
  • Stores user preferences

​
World Component (src/browser/components/world/)

The root component that assembles the 3D scene: 
<WorldCanvas>
  <Physics>
    <Camera />
    <Lights />
    <Sky />
    <Ocean />
    <Boat />
    <Nodes />  {/* Files & Folders */}
    <Minimap />
    <Audio />
  </Physics>
</WorldCanvas>

​
3D Rendering Pipeline

Gitlantis uses React Three Fiber, which creates a declarative API for Three.js:
  1. Canvas Setup - WebGL renderer initialization
  2. Scene Graph - React components = Three.js objects
  3. Physics Simulation - @react-three/cannon for collisions and floating
  4. Animation Loop - 60fps render cycle with useFrame hooks
  5. User Input - Keyboard, mouse, joystick controls

​
Key 3D Components

Boat (src/browser/components/world/boat/)
  • Player-controlled object
  • Keyboard navigation (WASD/Arrow keys)
  • Joystick support for touch devices
  • Physics body with collision detection
  • Custom hooks:
    • useBoat/keyboard - Keyboard input
    • useBoat/navigation - Movement logic
    • useBoat/floating - Bobbing animation
    • useBoat/compass - Direction tracking
Nodes (src/browser/components/world/nodes/)
  • Represents files and folders as 3D objects
  • Folders = Tall lighthouses
  • Files = Short buoys
  • Positioned in a grid layout
  • Clickable interactions:
    • Folders: Navigate into directory
    • Files: Open in VS Code editor
Ocean (src/browser/components/world/ocean/)
  • Infinite water plane
  • Animated waves using shaders
  • Dynamic regeneration based on boat position
Sky (src/browser/components/world/sky/)
  • Skybox/environment
  • Day/night cycle (future feature)
Camera (src/browser/components/world/camera/)
  • Third-person perspective
  • Follows boat movement
  • Configurable distance and angle
Minimap (src/browser/components/world/minimap/)
  • Overhead 2D view
  • Shows boat position
  • Displays nearby nodes
  • Toggleable visibility

​
UI Overlays (src/browser/components/ui/)

2D HTML/CSS overlays rendered on top of the 3D canvas:
  • Breadcrumbs - Current directory path
  • Compass - Navigation aid
  • Settings Modal - User preferences
  • Color Picker - Boat customization
  • Splash Screen - Welcome message
  • Loading States - Async operation indicators

​
State Management

Gitlantis uses Zustand for lightweight state management: Game Store (src/browser/hooks/useGame/store/) 
interface GameStore {
  boatPosition: [number, number, number]
  currentPath: string
  settings: UserSettings
  // ...
}
Extension Store (src/extension/store/)
  • Manages extension-level state
  • Caches directory listings
  • Tracks active webview panels

​
Custom Hooks

The src/browser/hooks/ directory contains reusable logic:
  • useNode/ - Node placement, collision, movement
  • useBoat/ - Boat controls and physics
  • useGame/ - Game state and settings
  • useExtension/ - VS Code API integration
  • useGit/ - Git operations
  • useWalker/ - File system traversal
  • usePersistence/ - State persistence

​
Communication Protocol

​
Webview → Extension

The webview sends messages using the VS Code API: 
vscode.postMessage({
  type: 'readDirectory',
  payload: { path: '/src/components' }
})

​
Extension → Webview

The extension responds with data: 
panel.webview.postMessage({
  type: 'directoryContents',
  payload: { files: [...], folders: [...] }
})

​
Message Types

Commands (Webview → Extension)
  • readDirectory - Get directory contents
  • openFile - Open file in editor
  • openExplorer - Reveal in file tree
  • listBranches - Get git branches
  • checkoutBranch - Switch branch
  • getSettings - Load user settings
  • updateSettings - Save settings
Events (Extension → Webview)
  • directoryContents - Directory listing results
  • branchList - Available git branches
  • settingsLoaded - User preferences
  • error - Operation failed

​
Performance Optimizations

Lazy Loading
  • Only load visible nodes
  • Directories loaded on-demand
Object Pooling
  • Reuse Three.js geometries and materials
  • Reduce garbage collection
Level of Detail (LOD)
  • Simplify distant objects
  • Reduce polygon count for performance
Debouncing/Throttling
  • Limit message frequency
  • Prevent overwhelming the extension process
React Suspense
  • Lazy load components
  • Show loading states

​
Build Process

  1. Browser Build (Vite)
    • Bundles React + Three.js code
    • Outputs to out/assets/
    • Generates index.html
  2. Extension Build (TypeScript)
    • Compiles Node.js code
    • Outputs to out/extension/
    • Creates CommonJS modules
  3. Packaging (vsce)
    • Bundles all assets
    • Creates .vsix file
    • Ready for distribution

Build docs developers (and LLMs) love

Get started for freeTalk to us