Sandcastle

A sand and water physics simulation with multiple renderers. Click to raise/lower sand, add water, watch it flow and erode terrain.

🎮 Live Demo

⚠️ Work in Progress - Under active development.

Features ✨

• 🏖️ Sand physics (collapse, angle of repose)
• 💧 Water physics (flow, surface tension, erosion)
• 🎨 Multiple renderers (2D top-down, isometric, voxel WebGL, Three.js 3D)
• 🖱️ Interactive terrain editing

Physics ⚛️

See PHYSICS.md for detailed explanation of how the physics engine works.

Summary:

• Sand: Cellular automata with angle of repose, collapses when slopes exceed ~35°
• Water: Surface harmonization with surface tension thresholds (0.05 wet, 0.8 dry)
• Both use random iteration to avoid directional bias
• Water checks evolving state during iteration for faster convergence

Renderers 🎨

See RENDERERS.md for detailed explanation of how rendering works.

Available renderers:

• Top-Down (Canvas 2D): Overhead view, fastest
• Voxel (WebGL): Instanced 3D cubes with lighting/AO
• Three.js (WebGL): Full 3D with PBR materials (mostly broken for now)

All support runtime switching without affecting simulation.

Architecture 🏗️

src/
├── core/
│   ├── simulation/
│   │   ├── base/
│   │   │   └── Grid2D.ts          # Base grid class
│   │   ├── sandgrid/
│   │   │   └── SandGrid.ts        # Sand height storage
│   │   ├── water/
│   │   │   └── WaterGrid.ts       # Water depth + velocity
│   │   ├── physics/
│   │   │   ├── SandPhysics.ts     # Sand collapse logic
│   │   │   └── WaterPhysics.ts    # Water flow + erosion
│   │   └── Simulation.ts          # Main coordinator
├── renderers/
│   ├── base/
│   │   └── Renderer.ts            # Renderer interface
│   ├── canvas2d/
│   │   ├── TopDownRenderer.ts
│   │   └── IsometricRenderer.ts
│   └── webgl/
│       ├── VoxelWebGLRenderer.ts
│       └── ThreeJSRenderer.ts
├── systems/
│   ├── GameLoop.ts                # Fixed timestep loop
│   └── SceneManager.ts            # Lifecycle management
├── input/
│   ├── InputManager.ts            # Mouse/keyboard handling
│   └── tools/
│       ├── SandTool.ts            # Raise/lower sand
│       └── WaterTool.ts           # Add water
└── ui/
    └── UIManager.ts               # Controls and debug info

Installation 📦

npm install
npm run dev    # development
npm run build  # production
npm test       # run tests

Usage 🎮

• Click/drag to raise sand, Shift+click to lower
• Select water tool to add water
• Adjust physics parameters in UI
• Switch renderers from dropdown

Tech Stack 🛠️

• TypeScript + Vite
• Three.js for 3D rendering
• Vitest for testing
• Canvas 2D for simple renderers

Fixed 60Hz physics timestep, variable render rate.

Made with humans 👨‍💻 using AI 🤖 🤝