Skip to main content

​
Overview

Gitlantis transforms your file system into an immersive 3D ocean world, where files and folders are rendered as interactive 3D objects floating on the water. The extension uses React Three.js and Three.js physics to create a realistic maritime environment.

​
World Architecture

The 3D world is composed of several core components that work together:
The WorldCanvas component serves as the root container for the entire 3D scene. It uses React Three Fiber’s Canvas to create a WebGL context.
<Canvas id="worldCanvas" className="!h-[100vh] !w-[100vw]">
  {children}
</Canvas>
Located in: src/browser/components/world/canvas/index.tsx

​
Ocean Rendering

The ocean is rendered using three-stdlib’s Water shader, which provides realistic water effects including reflections, refractions, and wave animations.

​
Implementation Details

<water
  args={[planeGeometry, sceneConfig]}
  position={tile.position}
  rotation-x={-Math.PI / 2}
  ref={(el: Water | null) => {
    if (!oceanRef?.current) return;
    oceanRef.current[index] = el;
  }}
/>
The ocean uses a tiled system that regenerates tiles dynamically as you navigate. This ensures infinite ocean rendering without performance degradation. Source: src/browser/components/world/ocean/index.tsx:13-22

​
Sky and Atmosphere

The sky uses Three.js’s procedural sky shader with atmospheric scattering: 
const skyParams = {
  rayleigh: 2,          // Controls blue scattering (higher = more blue)
  turbidity: 5,         // Atmospheric haze (lower = clearer)
  mieDirectionalG: 0.8,
  mieCoefficient: 0.05,
};
The sun position is calculated as a relative vector that follows the world offset, creating consistent lighting as you navigate.Source: src/browser/components/world/sky/index.tsx:22-27

​
File and Folder Nodes

Files and folders are rendered as 3D models positioned in the ocean world:
  • Files: Rendered using a dedicated file model
  • Folders: Rendered using a dedicated folder model
  • Collision Detection: Nodes detect when the boat collides with them
  • Click Interaction: Both keyboard collision and mouse clicks trigger file/folder opening
const sharedProps = {
  index,
  instance,
  nodeRef,
  isColliding,
  isBrowserEnvironment,
  isMinimapFullScreen,
  label: instance.data.name,
  model: isFile ? fileModel : folderModel,
  openOnClick: () => throttledOpenNode(instance.data),
};
Source: src/browser/components/world/nodes/index.tsx:38-52

​
Performance Optimization

Gitlantis uses several optimization techniques:
  • Suspense boundaries for lazy loading components
  • Tiled ocean rendering for infinite worlds
  • Throttled collision detection to prevent excessive file opening
  • Delta-based animations that adapt to frame rate

​
Loading and Transitions

The world respects the splash screen state and fades in smoothly: 
className={`${
  showSplashScreen ? "pointer-events-none opacity-0" : "opacity-100"
}`}
This ensures users see a polished loading experience before entering the 3D world. Source: src/browser/components/world/canvas/index.tsx:10-12

Build docs developers (and LLMs) love

Get started for freeTalk to us